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This manual defines and describes the use of the 8686 
Software Toolbox. The Toolbox is a collection of utilities 
which can help improve programmer productivity. 


Listed below is a brief description of each tool for quick 
reference. 


Tools marked with a "*" can utilize extra 8986 system 
memory, meaning they can execute more efficiently, process 
more symbols, and/or accept a larger variety of input. 


Text Formatting 
* SCRIPT batch text formatter 
MPL standalone macro processor 
* SPELL spelling checker program, plus dictionaries 
* WSORT SPELL dictionary compactor 


86286 Tools 
* OMC286 8£86 to 89286 object module converter 
E8@287 8@286-based 89287 emulator, 
plus initialization library E8@287.LIB 


Performance Analysis 
* PERF code performance analysis tool 
GRAFIT PERF map grapher 


Sorting 
* ESORT very flexible sort program 
* HSORT in memory heap sort program 
Miscellaneous 
* XREF list file inter-module cross reference tool 
plus XREF8@ for asm8@,asm48 listings 
pc floating-point calculator 
plus DC87, uses 8@87 hardware 
FUNC SERIES IIIE function key programmer 
PASSIF ha a purpose assertion checking and reporting 
too 
* COMP synchronized file compare program 


GLOSSARY 


UDI: 
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refers to the standard INTEL 8986/8988 based operating 
system service routine interface. 


For details, see the following manuals: 


Intellec Series-IV Operating and Programming Guide 
121753 


Intellec Series III Microcomputer Development 
System Programmer's Reference Manual 
121618 


iRMX 86 Programmer's Reference Manual, Part II 
146196 
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I. INTRODUCTION 


The iMDX Text Formatter (SCRIPT) formats an input text file 
under control of commands embedded in the text. SCRIPT is 
useable on any UDI-compatible 8986-based system with at 
least 96K of user memory. Output is to the DTC-KRS, DTC- 
39@, any line printer or UDI-supported file. 


SCRIPT uses the file handling capabilities provided by UDI. 
Input files are prepared using a separate text editor such 
as AEDIT, CREDIT, etc. (SCRIPT will concatenate input 
files, permitting the use of memory resident editors, even 
on large documents.) Uppercase-only files are fully handled 
by SCRIPT, as are upper/lower case files. 


Not all of the features described have been implemented in 
the current version of SCRIPT, but they are being specified 
to make sure the current design does not preclude their 
later implementation. Those features that are not 
implemented in the current version are hashed out in this 
document. 


II. INTERFACE SPECIFICATIONS 


A. User Interface 
1. Characters 


Certain characters in the input text cause special actions 
to take place. For example, a space delimits words, and 
ampersands surround text to be underlined. Many of these 
special functions can be assigned to a _ character of the 


users choice. In addition, a literal character (initially 
*) causes the the character that follows it to be treated as 
a plain text character. 


As far as the user is concerned, line boundaries in the 
input text are ignored. To make this happen, SCRIPT must 
take special action at the end of an input line. In most 
cases, it must add a space to the end of the last word on 
the line so that it doesn't run into the first word of the 
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next line. If the word looks like the end of a_ sentence, 
SCRIPT will add two spaces. If the word ends with a hyphen, 
however, it is assumed to be a hyphenated phrase, and no 
extra blanks are inserted. But, if the "word" is actually a 
dash made of two hyphens, a space is inserted. 


In £111 mode (see below), SCRIPT will add spaces after any 
word that looks like the end of a sentence to ensure that it 
is followed by at least two spaces. 


Many text formatters remove "extra" spaces found in the 
input file. Since it is desireable to have two spaces at 
the end of every sentence, these formatters must try to 
recognize the end of a sentence to do so. Also, they must 
provide a mechanism for inserting extra spaces when they 
really are needed (for special symbols to be added later, 
for instance). SCRIPT will never be as clever as its users, 
so if a user puts in spaces, SCRIPT will leave them there. 
The only spaces that SCRIPT will delete are those marking 
the beginning of a paragraph (see the AUTOPARAGRAPH 
command). 


2. Commands 


SCRIPT commands are block-structured. BEGIN and END 
commands bracket blocks, and internal variables such as 
margins and paragraph spacing may be given new values within 
the block. These new values hold from the point of 
assignment to the end of the smallest enclosing block, or 
until they are again reassigned. All such variables 
initially have default values. 


A command may appear anywhere in an input line. ‘The start 
and end of a command group are signalled by a special 
character (initially '/'). Multiple commands are separated 
by semicolons or linefeeds, and arguments are separated by 
commas. (Any of these characters may be used in command 
arguments by using the literal character in front of them.) 
A null command is tolerated so that other commands may be 
terminated by a semicolon. For most commands, arguments may 
be omitted and default values will be used. SCRIPT looks 
only at the first letter and the remaining consonants of a 
command, and accepts as a command any string of consonants 
that is the valid prefix of one of the commands’ listed 


below. Selected commands have alternative abbreviations in 
addition to this abbreviation rule. Commands may be written 
in any combination of upper and lower case. The commands 


(and their nonstandard abbreviations) are: 
ASIS - —- - END 


The ASIS ("as is") command causes a break and begins a 
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block, in which SCRIPT processes text in the NOFILL, 
NOJUSTIFY, NOAUTOPARAGRAPH mode. In this mode plain 
text will appear in the output just as it does in the 
input. (All other commands, such as SPACING, UPPERCASE, 
and LMARGIN, are active, however. Macros are expanded.) 


AUTOPARAGRAPH (AP) [-] i,s,t 


Sets a mode in which a null line or any line starting 
with a space is interpreted as the start of a new 
paragraph, i.e. as if it had been preceded bya 
PARAGRAPH command(this will cause a BREAK). The leading 
Sspaces(s) are removed from the input line. If any 
parameters are given, they redefine the defaults for the 
PARAGRAPH command in the current block. 


NOAUTOPARAGRAPH (NAP) 


Lines with leading spaces are interpreted just like 
other lines. The leading spaces are not removed. 


AUXFILE [n] {text} 
The "text" delimited by "{" and "}" is written to 


auxiliary file n. The default file is auxiliary file @®. 
(The mapping from auxiliary file numbers’ to physical 


files is established by an invocation control as 
described in Section III.) The text may be any string 
of characters that is balanced with respect to "{"-"}" 
bracketing. (Unbalanced braces may be introduced using 
the "literalizing" character. ) The text is not 
processed the same as text going to the main output 
file. Only macro calls within the "text" are expanded 


before writing to the file. All other SCRIPT commands 
and special characters are NOT processed. 


BEGIN [name] - - - END [name] 


BEGIN starts a block. The name is used for error 
checking with the name on the end command. END marks 
the end of a block. All parameters set within the block 
revert to their previous values. The parameters’ that 
could be affected are LMARGIN; RMARGIN; bar margin; 
AUTOPARAGRAPH; PARAGRAPH indent, skip, and test values; 


CENTER; FILL; JUSTIFY; LOWERCASE/UPPERCASE/NOCASE; 
SPACING; TAB settings; FLAG characters; drop character; 
bar character; and USPACE. The name on the END command 


should match that on the corresponding BEGIN command. 
It is possible to detect that an END command has been 
left out, and SCRIPT could try to correct the situation. 
(Names on blocks are not implemented in this version.) 
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Neither a BEGIN nor an END command cause a BREAK. 
BREAK [n] 


Ends the current output line and leaves n blank lines 
(regardless of the current SPACING mode). The default 
value of nis 9. Lines ended by explicit or implicit 
BREAKS are never justified. In an attempt to prevent 
"widows" (printing the last line of a paragraph alone at 
the top of a page), SCRIPT will allow a line ended by a 
BREAK to occupy the line after the "last" text line ina 


page. 
CENTER 


This command causes a BREAK and switches SCRIPT to’ the 
centering mode. Output lines are centered between left 
and right margins. Centered lines are not filled or 
justified. Lines with tabs in them are not centered. 


NOCENTER 


This command causes a break and turns off centering of 
output lines. Note: CENTER must be in effect at _ the 
END of an output line to cause the line to be centered. 
Thus, /begin; center/ ... /end/ will not generate a 
centered line because CENTER will be turned off by the 


/end/, before the end of the line. Because /nocenter/ 
causes a break before turning off centering, all lines 
between /center/ ... /nocenter/ are sure to be 


centered. 


/ COLUMN a tote A AOR ON A OF AA HK A. A 
/ f 4oe#& Ff 4 4F 4 LF FE FF 4 OE LE OL EF 4 
/ cian cgmmdénd/ cdus¢gs /a /brgak/ afd /switches/ouxpux tg 
/ f/ ¢olymn/n./ (Fhe/ dgfavlt/ cPlupin /is/ the /nexXt /defingd / 
/ f/coxyump plodvlo/th¢ nfXmb¢r gf ¢golvkmng.)/ Gutput/tox exch/ 
/ / c@lupn xs gen¥ tg a/ sgpayat¢ Puffer/ /Th¢n,/ when/ ap 
/ / dmpYicxt gr gxpYic7Yt ZOLYMN/copimaxd gwifch¢s gutput/to/a / 
/ f/coxyump that/is/th¢g sdme/as/or/is/ tg fhe/ 1gft/ of fLhe/ 
/ / crrgnt/ cglupin,/ /alY favégd /texXt zs putput/togetfer/ 
/ / fhofxt golfmng axe padded/with Blafxk Yings fo /maxch/ the / 
/ /lofpgegt /coxyum~. /Coxumps pflay/no# b¢ ldnggr xhap a/page./ 
/ f/ Oftsyde/a f~abYe,/COZUMM n/is/trgat¢d ds x PAGE/ cPgmmdnd/ 
/ / /Usé the FABLE /copmafd xo get/coxumn~ dymefsigns/ / / / 


COMMENT text 


This command is’ ignored. The comment text may not 
contain a semicolon. 
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DROP [n] [,c] 


Tabs to the n-th tab stop, "dropping" the character c as 
it. moves. If n is not coded or is ©, the next tab stop 
to the right is selected. If the selected tab stop is 
to the left of the current position, a BREAK is 
executed, and the new line is started at the tab 
position. If the current position is the selected tab 
position, no movement occurs. Drop characters are not 
generated to the left of the start of the line. c 
becomes the default drop character until the next /end/ 
or /drop,c/ command is executed. The drop character is 
initially ".". 


Example: /settabs +19,+20,+30,+48,+59; break/ 
/drop 2,-/+/drop/+/drop5/+ 
/drop4,*/ 

generates: 


--~----~--- +++ ------ $o--------4--- + -- 
KEK KK KEKE KEK KKK KKK KK KEK KKK KEKE KE KER KKK KEK EKKEEKE 


/ FIGURE p,m/- A -/ENB / / / f/f f/f / Sf f Ff 4 f SF Sf fF 
Lod Ff AAA LA MAA EA A AOD AL EK 
/ / This/copimapd gauges/a BREAK./ If epfough gpage Yxemding of 
/ / fhe/cuyrept pag¢ tg sKip/n /lifes/ afd /pryznt/ the /text / 
/ /geyverdted by the 7YnpAt Petyeex the paixved/FIGURK apd END/ 
/ / coémmdndg, SCRIPT/dogs go./ O¢hexwige,/ the /figurg fex¥ 
/ / ¢nda/ cdptzon/ axe /saved/ f¢r /th¢ bé¢gifxnipxpg Pf ~he/next / 
/ /page,/and ngrmdl fex¥ may gonfinfe gn ¢he/cuyrept /page./ 
/ / Aftex fhe/ figufe /is/ pxyacéd /on/ a/ pdge/ BREAK ph ig 
/ ¢éxegutéd./ The Lighre/text zs XmpYicz7tly¥ efclgsed in /a / 
/ /beginfend pPlog¢gk /and pay/no¥ cgntdin/a KEEP, FIGBRE/or/ 
/ / PAGE/copimapd./ (At /thzys fim¢, FIGBRE/m,x~ -/- # END/ is 
/ / ¢quzivazeny tg PAGE/ BEGIM -/- 4 EXD;/ BREAK m/) / / / / 


FILL 


Sets FILL mode (the initial condition), which causes 
words from separate input lines to run together to make 
output lines as long as possible without overflowing the 
left and right margins. 


NOFILL 
This command causes a BREAK and clears FILL mode. The 
end of every input text line causes the end of an output 
line. Blank input lines cause blank output lines. As 


in the FILL mode, leading blanks on a line ora null 
line will initiate an AUTOPARAGRAPH if that mode is 
active, and if JUSTIFY is set, the line will be 
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justified unless it is followed by a null line . Under 
NOFILL, if an input line is too long for the output 
margins, the RIGHT MARGIN IS IGNORED and text is allowed 
to extend indefinitely to the right. Note that lines 
containing only commands are not treated specially in 
NOFILL mode--they will generate blank output lines. 


FLAG function [,character] 


Assigns a special function to the given character. This 
assignment holds until it is reassigned, or until the 
end of the block. Whatever character previously held 
the special function loses its special function. If no 
character is given, this command does nothing but 
"unspecial" the old character. Any other special 
function held by the given character is also lost. 
Legal flag functions, together with the flag's effect, 
are: 


ASCII Marks the beginning of a decimal number that 
is interpreted as the ASCII code for a 
single character. 


BACKSPACE Generates a backspace code in the output. 


CONTROL The next character is treated as an 
"invisible" control character. The EXTEND 
Or LITERAL or ASCII flag characters may be 
used to enter the control character. 


COMMAND Marks the beginning and end of a command 
string. Initially '/'. 


DELIMITER Separates arguments in a macro call. The 
default value is "\". 


DIVIDE Marks where a word can be divided. If it 
helps the output line look better, SCRIPT 
divides the word where this’ character 
appears (and inserts a hyphen). Otherwise 
the character is discarded. For example: 


/begin; fill;just; 1m4@;rm69; FLAG DIVIDE, ‘/ 
Anti*‘dis‘estab‘lish*mentar‘ianism is 

super ‘cali*fragil*‘istic*expi‘alidou*sious!? 
/break; end/ 


generates 
Antidisestablish- 


mentarianism is 
supercalifragil- 
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EXTEND 


LITERAL 


MACRO 


NTB 


SUBSCRIPT 


SUPERSCRIPT 


isticexpialidou- 
sious!? 


Adds the parity bit to the following 
character, producing an extended character 
set. All extended characters are assumed to 
be one space wide. 


Treats the next character as a simple text 
character without changing it or 
interpreting it. Initially '*'. 


Marks the beginning of a macro call, macro 
formal parameter, or macro definition. 
Initially "$". 


Stands for a Non-Trivial Blank. The non- 
trivial blank prints as a blank, but is 
treated as an ordinary text character, 
otherwise. Initially a tilda (i.e., 7EH). 
Marks the beginning of a subscript 
expression. On the DTC-30@ the characters 


that follow the flag character are printed 
3/48-th inch lower than the preceding 
characters. on other devices, the 
characters are lowered a full line. 
Subscripting is ended by a SUPERSCRIPT 
character. Subscripts may be subscripted to 
a depth of 64. 


Marks the beginning of a superscript 
expression. On the pDTC-389 the following 
characters are printed 3/48-th inch higher 


than the preceding characters. On other 
devices, the characters are raised a full 
line. Superscripting is ended by a 


SUBSCRIPT character. Superscripts may be 
superscripted to a height of 64. 


Example: 


"/ FLAG BCKSPC, *; FLAG SBSCR,{; FLAG 
SPRSCR,}; 1lm+7;rm-7/ Each a{i} has a cooling 
factor equivalent to e}(x-y}3{){, which 
means that each M}2{*‘{a{i},b{j}} is only 
Marginally stable at 4@O}o{F. On the other 
hand, a larger coefficient of cooling, with 
the appropriate scale factors applied, would 
not necessarily mean stability would return 
at 450}o{F." 


SCRIPT 8886 SOFTWARE TOOLBOX, V1.1 


would produce 


Each a has a cooling factor 
i 

3 
(x-y ) 

equivalent to e , Which 

2 

means that each M is only 
a 1b 
ij 

° 


marginally stable at 4@@ F. 
On the other hand, a larger 
coefficient of cooling, with 
the appropriate scale factors 
applied, would not necessarily 
mean stability would return at 
° 
450 F. 


UNDERLINE Marks the beginning and end of text that is 
to be underlined. Spaces not in the margins 
but between underlined words are underlined 
according to the setting of the USPACE and 
NUSPACE commands. Initially '&'. 


FOOT/EFOOT/OFOOT [left] [,[middle] [,right]] 


Specify the footers to be placed on each page. EFOOT 
specifies the footer for even-numbered pages, OFOOT 
specifies the footer for odd-numbered pages, and FOOT 
Specifies the same footer for both even- and odd- 
numbered pages. The left string is justified to the 
left margin in effect at the time of the command, the 
middle string is centered between the margins, and_ the 
right string is justified on the right margin. If the 
center string consists of one non-blank character (other 
than '#'), that character is replicated throughout the 
central field (from the end of the right string to the 
beginning of the left string). When the footer is 
printed, a number sign (#) is replaced by the current 
page number. The foot is initially empty. 


HASH [n] [,char] - - - ENDHASH [n] [,char] 


The HASH-ENDHASH commands delimit a region of text which 
will be overstruck with "char"s when printed. The 
region will be overstruck only if the current hash level 
(set by the HASHLEVEL command) is n or less. Hash 
regions to be printed may not be nested. The initial 
"char" value is "/". The hash character value is not 
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affected by the nesting of BEGIN-END blocks. HASH 
blocks are used in this document to "Shade" the features 
that are not supported in the present release of SCRIPT. 


HASHLEVEL [n] [,Hmar] [,Hoft] 
HASHLEVEL sets the current hash level and sets two 


parameters that control the overstriking operation. 
Within a HASH-ENDHASH region, the overstriking "char"s 


are printed between columns "Hmar" and width-"Hmar" 
separated by "Hoff" spaces. From line to line, the 
first column where the hash "char" is printed cycles 
from "Hmar" to "Hmar"+"Hoff"-1. The initial settings 


are equivalent to a HASHLEVEL @,2,3 command. HASH 
blocks in this document use the initial settings for 
Hmar and Hoff. 

HEAD/EHEAD/OHEAD [left] [,[{middle] [,right]] 


Similar to FOOT commands, but specifying page headings 


for each page, or each even-, or odd- numbered page. 
The initial heading is /head,,PAGE #/. To turn off a 
head or foot, issue the appropriate command with no 


parameters. The end of a block does not cause a head or 
foot to revert to its previous value. 


INDENT [-] i 


This command causes a BREAK. The next line of output is 
"indented" i spaces from the left margin. If a minus 
Sign precedes "i", the line is started i spaces to the 
left of the left margin, if possible. 


ITAB [n] 


Tabs to the n-th tab stop and establishes the left 
Margin there, until the next implicit or explicit BREAK 
command. If n is not coded or is @, then the next tab 
stop to the right is selected. If the selected tab stop 
is to the left of the current position, a BREAK is 
executed, and the new line is started at the tab 
position. If the current position is the selected tab 
position, no movement occurs. When the BREAK occurs, 
the left margin will be set to whatever it would have 
been, had no ITAB command been present. ITAB is 
Similar to the MTAB command, except that the left 
margin set by ITAB is only in effect until the next 
BREAK. 


ITAB is useful in formatting lists of short definitions. 
For example, the following input could be used to 
generate the initial flag definitions given above: 
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/begin; ap @,1,9; settabs +12/ 


ASCII/itabl/Marks the beginning of a /erv3/decimal/erv3/ 
number that is interpreted as the ASCII code fora 
single character. /vev3;rev3/ 


COMMAND/itabl/Marks the beginning and end of a command 
string. Initially '*/'. 


DIVIDE/itabl/Marks where a word can be divided. If it 
helps the output line look better, SCRIPT divides the 
word where this character appears (/rev3/and 


JUSTIFY 


Sets JUSTIFY mode, in which every output line not ended 
by a BREAK is expanded by inserting full or partial 
spaces (depending on _ the invocation option) to right- 
justify the text on the right margin. Blanks are 
inserted starting from the left or right depending on 
the parity of the line number. No blanks are inserted 
to the left of the left margin, to the left of the first 
word on the line, to the left of a tabulated word, or 
anywhere in a centered line. JUSTIFY is the initial 
mode. 


NOJUSTIFY 


Turns off JUSTIFY mode. No blanks are inserted into the 
output line, making an uneven right margin possible. 


KEEP - - — ENDK 


The KEEP command causeS a BREAK. If the output text 
generated between paired KEEP and ENDK commands will fit 
on the current page, SCRIPT will leave it there. 
Otherwise, a new page is started and, after any pending 
figures have been placed on pages, the KEEP text is 
placed on that page. KEEP may not contain a PAGE, KEEP 
or FIGURE command. (At this time, KEEP - - - ENDK is 
equivalent to PAGE; BEGIN - - - END.) 


LENGTH n [,[hm] [,{tm] [,{bm] [-f£m]]}]] 


16 


Declares the length of the paper to be an” lines and 
establishes the vertical margins for headers, text and 
footers. With 1/6 inch spacing, 11 inch paper is 66 
lines long and 14 inch paper is 84 lines long. hm 
specifies the number of blank lines above the header; tm 
specifies the number of lines above the first line of 
text (must be greater than or equal to hm); bm specifies 
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the number of lines after the last text line to the 
bottom of the page; and fm specifies the number of lines 
below the footer to the bottom of the page. The initial 
settings are equivalent to /LENGTH 66,2,6,6,2/, so that 
the default paper length is 66 lines, the heading starts 
on line 3, text starts on line 7, the last text line is 
7 lines from the end of the paper, and the footer is 
placed on the third line from the end. 


LMARGIN [+ | -] n 


This command sets the left margin and causeS a BREAK . 
If a plus or minus sign precedes n, the previous left 
margin is incremented or decremented by n, respectively. 
The initial value is zero. 


SCRIPT outputs a line at a time to the output file. 
After writing out a line, it then sets the left margin 
for the next output line. Once set, the left margin for 
a line does not change. That is why, for example, the 
LMARGIN command causes a= break: so that the text 
following the LMARGIN command is indeed placed on a line 
with the specified left margin. 


LOWERCASE 


Uppercase letters in the input file are converted to 
lowercase. The LITERAL flag (initially *) can override 
this conversion. This is the initial mode. 


MTAB [n] 


Tabs to the n-th tab stop and establishes the left 
margin there. If n is not coded or is @, the next tab 
stop to the right is selected. If the selected tab stop 
is to the left of the current position, a BREAK is 
executed, and the new line is started at the tab 
position. If the current position is the selected tab 
position, no movement occurs. Also see the ITAB 
command. 


MTAB is useful in formatting lists of short definitions. 
For example, the following input generated the initial 
flag definitions given above: 


/begin; settabs +0,+12/ 
/skip;ml/ASCII/m2/Marks the beginning of a 
/erv3/decimal/erv3/ number that is interpreted as the 


ASCII code for a single character. /rev3;rev3/ 


/skip;m1/COMMAND/m2/Marks the beginning and end of a 
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command string. Initially '‘/'. 


/skip;ml/DIVIDE/m2/Marks where a word can be divided. 
If it helps the output line look better, SCRIPT divides 
the word where this character appears (/rev3/and 


NOCASE 
No case conversions are done. Lowercase is not 
converted to uppercase; uppercase is not converted to 
lowercase. 

NUMBER [+ | -] n [,format] 
Enables the output of page numbers. If n appears, it 


sets the page number for the current page (the one on 
which the number command would have appeared if it were 
text mot in a KEEP or FIGURE.) The new number will be 
printed in the head of the current page if the number 


command precedes all text on the page. If a plus or 
minus sign appears, the current page number is 
incremented or decremented, respectively. The format, 
if it appears, is one of 1, I, i, A, or a, to signify 
arabic numbering, Roman numerals (in upper or lower 
case), or lettering. The page number format is 


initially, "1". 


i aaa ce a ae a a an a eae a ae a 
/ ff f f LF F°4 FT F FV SF 4 FF 
/ / Béha¥es/ es "Begin /nofe;/lm#15/ rph-1B; skip 2/ ‘tp 34 
/ / Pegxn;/cepteyx/ ~ex¢ /gndf skips" /If/th¢ fexzx for/ the / 
/ /tifle/dogs fot/appeay, ~he/woxd YNOTE"/is/ceptexeds/ the/ 
/ / ngte/is/enfed/by/"/égnd/nofe/y. /Thére/ ig flo /automdti¢ 
/ / kip a¥ the gnd/of/th¢g ngtef / / / / / / / / / Ff 


PAGE/EPAGE/OPAGE 


This command causes a BREAK, forces a switch to column 1 
and ends the current page. The foot for the page is 
printed and the head for the next page is set up to be 
printed before text is added. If the PAUSE switch is 
specified, the command rings the console bell and waits 
for input. Because a NUMBER command may follow the PAGE 
command, the header is not printed until a complete line 
is ready for the page. If EPAGE (OPAGE) is executed on 
an even (odd) page, the following odd (even) numbered 
page is left blank. 


PARAGRAPH [-] [i] [-{s] [,t]] 


Behaves like /skip s; testpage t; indent [-] i/. If any 
of i, s, or t are missing, defaults are used. These 
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are initially 5, 1, 2, but they can be reset in a block 
by the AUTOPARAGRAPH command. Notice that the skip s 
causes a BREAK 


REVISION [date] [,ch] - - - ENDREVISION (ERVSN) [date] [,ch] 


Defines a block of text around which marginal revision 
"bar"s are to be printed. Within such a block, the 
character last specified in a REVISION command is 
printed in the columns established by the VERSION or 
TEXT command. The initial revision character is "|". 
NOTE: The revision character is not affected by the 
nesting of BEGIN-END blocks. A REVISION command toggles 
the printing of revision characters only if the 
specified date is the same as or later (greater) than 
the current VERSION date, or if no date is specified. 
The date is specified as one to three numbers separated 
by hyphens, which are interpreted as dd, mm-dd, and mm- 
dd-yy, respectively. Revision blocks for the same date 
may not be nested or overlapped. But, revision blocks 
for different dates may be nested and/or overlapped. Up 
to 16 revision blocks may be overlapped at any point in 
the text. ( /rev,*/...ferev,!/ brackets this section. 
Revision characters appear on this page only.) 


RMARGIN [+ | -] n 
Sets the right margin to n, unless a plus or minus” sign 
precedes n, in which case the right margin is 
incremented or decremented by n,_ respectively. The 
longest line that will fit between the margins is 
(rmargin-lmargin) characters long. (Under NOFILL, the 


right margin is ignored.) 
SETTABS [+ | -] n [,] ... 


Sets tab stops at the specified positions. A position 
is relative to the left margin if its specification is a 
signed number. The tab stops must be given in 
(absolute) ascending order. Previous tab settings are 
lost (for the current block). Only TAB, MTAB,ITAB,and 
DROP commands in the input cause tabbing in the output 
line. No tabs stops are set initially. 


The tab stops are numbered 1, 2, 3, ... Tab stop @ is 
used to represent "the next tab stop". If the position 
is unsigned, then the lowest number permitted is l. 


SPACING n [,T] 


Sets the line spacing such that n-l blank lines are 
printed between each line generated by the input text. 
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The initial spacing is 1. If "T" is coded after the 
spacing value, only lines that have text on them will be 
followed by the n-l blank lines. (The "T" mode is 
useful for generating drafts that will need extensive 


revisions.) 


SPREAD [left] [,[middle] [,right]] 


This command causes a_ BREAK. The left, middle, 


right strings are formatted into a line as in the 


F 


and 
oot 


or HEAD command. The line is then added to the output. 


SKIP [n] 


This command causes a BREAK, then skips n lines or until 
the top of a page is reached, whichever comes first. 
Note that this may be zero lines if already at the top 


of a page. An exception is made if the top of a 


p 


age 


was reached by a PAGE command, so that SKIP immediately 
following a PAGE will indeed skip. If n is missing, 
is assumed. Each blank line generated by SKIP is 


"spaced" under the control of the SPACING command. 


1 


/ stoP/ / / sf / Sf 4 4 LS 4 4 4 4 4 4 4 4 4 ST 
AoA AF AF LF AF A A A DAF DF A dF OD 
/ / ‘this/copimapd gauges/oufgpus% tg sfop/at/ the /pozynt/ wher¢g 
/ / the/ cdmménd/ whuld hdve/appeaxyed/if/it/weye fex¥. /This / 
/ /is/us¢fuyY f¢r ghapgipg ¢xhe/typge /elgmefxt,/ fgr /exdmpLe./ 
/ 


/ / Ik hes fo gffgct/unYesg oftpxAt xs xo ¢xhe/DT¢. / / 


TAB [n] 


/ 


Tabs to the n-th tab stop. If n is not coded or is @, 


the next tab stop to the right is _ selected. If 


the 


selected tab stop is to the left of the current 


position, a BREAK is executed, and the new line 


is 


started at the tab position. If the current position is 
the selected tab position, no movement occurs. [Note: 
/tab/ must be used to tabulate the output text properly. 
SCRIPT does not recognize the tab character, “I (@9H), 


as a tab command. ] 


/ TABLE [# |/-]/left:/ wYdth, /../ -/- A EMD / / / / ow / rs 
be Bi A A / 


LF £ SF LF f oD FD FB FE 


/ / Dglipitg ¢ fabye./ The FABLE /stdtepeny b¢gipis i pyock. 
/ f/ &nd/defings ~ nfmb¢r Pf ¢golvmng by spec7{fyzZng/thgir/lefst / 
/ /text /maygips fang yid¢ghs/ /If/ a/ pyus/ oy mynug szgn/ 
/ / prfecédeg a/left /maxycip, /it/ ig set/ rglavyivé fo /th¢ 
/ yj guryeny lgft/mafgip; pth¢rwyse/it/is/abgolute/ / / / / 


tf fb 


i a ae Ld kA A Et A OL OS 
/ salad BuiYdipg /a /taple/ $CRZPT/ mdinfaips /a /sex of 
/ / MARGIN, RMARGIM vdlugs for/ edch/ cglupin:/ PBMARGIY 


14 


/ / 
zs / 


8986 SOFTWARE TOOLBOX, V1.1 SCRIPT 


/ f/ingtiglly Zerg (high goryesponds Yo Zhe/left pargin/of/ 
/ / the golfmny; KMARGIM ig ifitzalYy “¢he/coxump w7Ydth. /Th¢ 
/ / ¥MARGIX gnd/ RMARGIN/ cgnty¥olg w%1l/chang¢ thes¢ vdlugs / 
/ /fo¥ the golfmn/in/whych/thg¢y gccfr./ The f~abse zis /buzlt/ 
/ / f¥om/ tgp Yo Potxom/ afd Yef¥ tg rzygh¥, Msipg ~he/COLUMW 
/ / g¢ommand tg sfit¢h /bezywegn /cofum~s./ The/ cPlupins/ aye / 
/ /nupibexed/ ffom/left fo Yigkt gtayxtipg At XZ. /A Fabse play/ 
/ / ngt gongaifi a/FIGURZ, PAGR, FABLE gr KEEP cpmmdand/ But/ 
/ / ABLES/may appedr WitKin/a FIGPRE/or/KEZP./ / / / / 


TESTPAGE (TP) t 


If fewer than t lines are left on the current page, a 
PAGE command is executed. This command always causes a 
break. 


TEXT lmargin,width [,bmargin] 


This command defines the left margin and width for each 
text line. After executing /TEXT L,W,B/, LMARGIN zero 
will correspond to position L+l of the page, and 
revision bars will be drawn at physical positions B+tl 
and wW-B. The initial text margins are set by /TEXT 
@,85,2/. (At this time, the left margin value is 
ignored.) 


UPPERCASE 


In this mode, all lowercase letters are converted to 
uppercase. This mode is cancelled by the NOCASE 
command, but may coexist with LOWERCASE for interesting 
effects. (tHIS SENTENCE WAS TYPED IN NORMAL UPPER/LOWER 


CASE, BUT GENERATED UNDER /uppercase; lowercase/ 
CONTROLS. ) 

USPACE 
Flags that spaces are to be underlined whenever 


underlining is specified. This is the normal condition. 


/ NBSPKCE/ / / / / f/ f{ ff £ £ £ 4 4 4 4 4 4 TF 
Af 4 FU 4 LF 4 4 LF 4 FF TF 4 FT FT 
/ / Fxagg that/spdceg axe fot/to/be/underYingd./ / / / / 


VERSION [n] [,m] 


Sets the document version number (date) to "n" and the 
bar margin indent to "m". After this command is 
processed, only REVISION commands referring to VERSION 
"n" or higher will toggle revision bar printing, and the 
revision character will be printed in physical positions 
mand "TEXT width"-m-1 of the output line. The version 
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number is written in the same form as described in the 
revision command. A VERSION number of 9 will activate 
all REVISION blocks in the file, and a VERSION number of 
65535 (the largest possible) will deactivate all 
REVISION blocks. 


3. Macros 


To enhance the usefulness of SCRIPT, a limited macro 
processing feature is provided. The user may define 
parameterized macros that are unconditionally expanded when 
scanned by SCRIPT. All macro processing is performed before 
any other SCRIPT command or special character. Thus, a 
macro expansion may generate SCRIPT commands or _ special 
character sequences as well as the text to be included in 
the output document. 


Macro processing is initiated by the scanning of the MACRO 
flag character. The initial macro flag is "%", but this may 
be changed by the FLAG MACRO command to any character’ the 


user desires. To get the macro flag character through the 
macro processor without initiating macro processing, the 
macro flag character must be doubled. (Note: the 


literalizing flag character will NOT literalize the macro 
flag character.) 


The name of the macro to be processed immediately follows 
the macro flag. A macro name begins with a letter and 
continues with any contiguous sequence of digits and upper- 
or lower-case letters. The case of a letter in a macro name 
is significant. Some examples are %Chapter, %Date, %Notel, 
and $Note2. 


If the macro name is followed immediately by an "=", a new 
definition is attributed to the macro name. In its simplest 
form, the definition is all of the characters between the 
"=""and the end of the input line. For example: 


sDate=6/14/82 
SNotel=/skip; begin; lm+5; rm-5/ %@ /end; skip/ 


defines two of the above macros, $Date and $Notel. 


A macro definition may be continued onto several lines by 
starting each continuation line with the macro flag followed 
immediately by an "=". For example, %Chapter and %Note2 are 
defined as follows: 


eChapter=/aux{/t1/%9@ /t2/%1 /drop6/ %pn 
%=}; skip; tp6/%@. %1 

%Note2=/aux {%Notel1[%1l] 

%=}/%Notel[$1] 
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When expanded each of these macros will generate two lines 
of input. 


Formal macro parameters are denoted by the flag character 
followed by a single digit (as %@ and %1 in the definitions 
above). Hence a macro may have at most ten formal 
parameters. Whenever a formal parameter is scanned by the 
macro processor, the current input source is stacked and the 
input to SCRIPT is switched to the value of the 
corresponding actual parameter. When SCRIPT reaches the end 
of the actual parameter, input is restored to the character 
following the name of the formal parameter in the macro 
definition being expanded. Outside a macro expansion a 
parameter reference is replaced by the null string. 


If the macro name is not followed by an "=" the macro name 
is expanded according to its definition. The expansion 
proceeds in two steps: first the actual parameters are 
collected from the input and stored within the macro 
processor; then the current input source is stacked and 
input to SCRIP? is switched to the definition of the macro. 
When SCRIPT reaches the end of the definition, input resumes 
with the character immediately following the macro call. 


The actual parameters to the macro call, if there are any, 
are enclosed in square brackets immediately following the 
macro name. The actual parameters are separated by the FLAG 
DELIMITER character (initially "\"). (Note: an empty 
parameter list ("[]") may be used to delimit the right end 
of a parameterless macro call which must be embedded in 
text.) The only restrictions on the form of an actual 
parameter are that 1) it must be balanced with respect to 
square brackets and 2) it must contain no flag delimiter 
character that is not nested within square brackets. (Note: 
the macro flag character may be used _ to literalize an 
unbalanced square bracket or flag delimiter character.) 


As an actual parameter is collected, only formal parameter 
references within it are expanded; macro calls are not 
expanded until the actual parameter is substituted into text 
outside of a macro argument. A formal parameter reference 
within an actual macro argument is "expanded" by inserting 
the character sequence currently associated with it directly 
into the sequence that defines the actual parameter being 
collected. Nothing is expanded or parsed in this insertion 
process. Hence, the call to g%Notel within %Note2 is 
guaranteed to parse correctly regardless of the value of its 
second parameter ($%1). 


If the flag macro character is not followed by a letter or 
digit, the flag macro character serves to literalize it with 


17 


SCRIPT 8086 SOFTWARE TOOLBOX, V1.1 


respect to macro processing. 

Predefined Macros 

The only predefined macro is %pn, which always expands to 
the decimal representation of the current document page 
number. 


B. System Interface 


SCRIPT uses the UDI interface to the RUN operating system. 


Cc. Files used 


SCRIPT transcribes text from a list of input files toa 
single output file. Error messages are directed to the 
console. The user may optionally generate additional output 
files using the AUXFILE command. No other files are used. 


III. OPERATING SPECIFICATIONS 


A. Product Activation Instructions 
SCRIPT is invoked by the command: 
SCRIPT <input list> [TO <output spec>] {<switch>} 


where <input spec> is a list of file specifications 
(wildcard characters are not permitted), <output spec> is a 
Single file specification (wildcard characters are not 
permitted ), and <switch> is one of the following: 


DTC output is formatted for printing on the DTC-399 
terminals. This enables the use of some special 
characters. Partial spacing is NOT enabled. 


Pitch is established by the switch on the DTC. 


FIRST(n) The first page numbered n is the first page 


output. 

LAST (n) The first page numbered n, is the last page 
output. 

PAUSE SCRIPT types a bell and waits for console input 
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before printing each output page except the first. 
This is useful if output ona letterhead, for 
example, is desired. 


PITCH(n) Indicates that partial spacing on the DTC is to be 
used. Full spacing is set at 6@/int(6@/n) 
characters per inch. 


IMDEX / Pam¢s g¢ fzXle/or/ fyleg fo /regeiye /th¢ gocfmext / 

ff £ pinged F SOL Ff F OL SO TLS CE OF 

AUXFILEn = filename 
Names the file to receive text sent to auxiliary 
file n. If the source text uses auxfile i, but no 
corresponding "AUXFILEi = filename" control was 
issued in the invocation, then SCRIPT will 
dynamically create an AUXFILE for i. This file 
will have the same root as the output file, and 
the extension will be "AFi". 


If SCRIPT is required to generate a default 
auxfile, then the message 


<file> used as auxfilei 


will be output to the console. 


SCRIPT signs on with the console message: 
<system-name> Transcription Service, V1.1 


When the output file is opened, SCRIPT issues the console 
message: 


*Transcribing <input file> to <output file>. 
When a new input file is opened for the output file, SCRIPT 
annotates this with the message: 

*Pranscribing <input file> to <output file>, line # 


The message 


*Finished in line # of <input file>--<output file> has # lines 


announces the end of execution, transcription is complete. 
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B. Summary of Error Conditions 


Any nonzero status returned by a UDI call causes SCRIPT to 
print the error using the following format: 


I/O OPERATION - 


FILE: <file> 
OPERATION: <script _msg> 
ERROR: <udi_msg> 


<File> is the name of the file that the operation was being 
attempted on. <Script msg> names the operation SCRIPT was 
trying to perform. ~<Udi msg> is the text returned by the 
UDI procedure DQSDECODESEXCEPTION. Other errors and special 
situations detected by SCRIPT generate the following 
messages to the console: 


*OUT OF MEMORY in line # of <input file> 
SCRIPT does not have enough room for I/O buffers. 


*TOO MANY WORDS in output line in line # of <input file> 
SCRIPT can't process more than 190 words per line. 


*output line TOO LONG in line # of <input file> 
The limit is 2@@ characters per line. 


*WORD TOO LONG in line # of <input file> 
The limit is 1@@ characters per word. 


*TOO MANY underline flags in line # of <input file> 
Only 48 underline flags per line are permitted. 


*Undefined Tab or Tab Index in line # of <input file> 
In a TAB n command, n is greater than the number of tabs 


currently set, or in a TAB command, no tabs are defined 
beyond the current position. 


*Too many tab settings in line # of <input file> 
The limits is 109 tab stops. 


*Tab setting is out of order in line # of <input file> 
Tab settings must be specified in ascending order. 


*STACK OVERFLOW in line # of <input file> 
The stack is used to save command values changed inside a 


begin block. Each value saved requires 3 or 6 bytes 
depending on its’ size. 290 bytes are allocated for the 
stack. 


*NESTING TOO DEEP in line # of <input file> 
BEGIN-END blocks may be nested only 1 deep. 
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*TOO MANY ENDS in line # of <input file> 


*TWO PLACES FOR PAGE NUMBER in line # of <input file> 
In a head, foot, TOC or SPREAD. 


*Unknown COMMAND "“<command>" in line # of <input file> 
*Unknown FLAG “<command>" in line # of <input file> 


*PIGURE nested within KEEP or FIGURE in line # of <input 
file> 


*KEEP nested within KEEP or FIGURE in line # of <input file> 


*Unexpected "<command>" in line # of <input file> 
Such as an ENDK out of place. 


*Unexpected REVISION command in line # of <input file> 
Consecutive REVISION commands not separated by an 
ENDREVISION command. 


*TOO MANY (17) active revision levels in line # of <input 
file> 


*Unexpected END REVISION command in line # of <input file> 
Consecutive END REVISION commands not separated by a 
REVISION command. 

*MARGINS OVERLAP in line # of <input file> 

*Terminating COMMAND FLAG expected in line # of <input file> 


*TOO MANY COMMANDS 
This is a SCRIPT error and should not appear. 


*")" expected following "<switch>" 

The parameters on the INDEX, LAST, FIRST, and PITCH switches 
may be enclosed in parentheses. 

*UNKNOWN SWITCH "<switch>" 

*incorrect COMMAND LINE format 

Invocation line did not end with a CR, LF, ESC or command 
flag. 

*CR not followed by LF in line # of <input file> 

*Unbalanced macro parentheses in line # of <input file> 


*Undefined macro in line # of <input file> 


*Excessive macro arguments in line # of <input file> 
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*Unexpected HASH command in line # of <input file> 


*Unexpected ENDHASH command in line # of <input file> 
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Appendix I: Single Letter Abbreviations 


QAmMAVTAwW YS 


RUS OS Se Se NS Pa OE RS 0) es ee 


AUTOPARAGRAPH 
BEGIN (not BREAK) 
COLUMN 

DROP 

END 

PILL 


INDENT 

JUSTIFY 

KEEP 

LENGTH 

MTAB 
NOAUTOPARAGRAPH 
OFOOT 

PARAGRAPH 


RMARGIN (not REVISION) 
SKIP 

SETTAB 

TAB 

USPACE 

VERSION 


V1.1 
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Appendix II: Defaults 


AUTOPARA (TRUE), /* INITIAL SPACES CAUSE PARA */ 
LOWERCASE (TRUE), /* CONVERT UCASE TO LCASE */ 
FORCEUP (FALSE), /* CONVERT LCASE TO UCASE */ 
FILL (TRUE), /* FILL LINES WITH WORDS */ 
CENTER (FALSE), /* CENTER LINES BETW MARGINS */ 
JUSTIFY (TRUE), /* ADD SPACES TO LINE UP RM */ 
CYCLING (FALSE), /* CYCLING PAGE NUMBER POS.*/ 
REVISING (@), /* Active REVISION BARS */ 
REVLINE (FALSE), /* ADD REVISION BAR TO LINE */ 
HASHING (FALSE), /* ADD HASH MARKS TO LINE */ 
HASHLINE (FALSE), /* ADD HASH MARKS TO LINE */ 
TOPPAGE (TRUE), /* SITTING AT TOP OF PAGE */ 
TOPBYCMD (TRUE), /* AT TOP CUZ COMMAND */ 

DTCSW (FALSE), /* OUTPUTTING TO DTC-309 */ 
PAUSESW (FALSE), /* PAUSE BEFORE EACH PAGE */ 
BROKEN (TRUE), /* RECENTLY ISSUED A BREAK */ 
PAUSE (FALSE), /* PAUSE AFTER EACH PAGE */ 
SPACESNULL (TRUE), /* SPACE AFTER NULL LINES */ 
OUTPUTING (TRUE), /* DON'T SUPPRESS OUTPUT */ 
FIGURING (FALSE), /* Building a Figure */ 
FIGUREBREAK (9), /* LINES to BREAK after FIGURE */ 
KEEPING (FALSE), /* Building a KEEP block */ 
LMARGIN (@), /* LEFT MARGIN */ 

INDMARGIN (@), /* LEFT MARGIN + INDENT */ 
RMARGIN (65), /* RIGHT MARGIN */ 

BarSMargin (2), /* Offset for Revision Bar */ 
TextS$Margin (0), /* Offset for text */ 
HashS$Margin (2), /* Offset for Hash Marks */ 
Hashsoffset (3), /* Increment between Hash Marks */ 
HashsCycle (9), /* Initial Increment for Hash Line */ 
WIDTH (85), /* PAGE/COLUMN WIDTH */ 
PAGELEN (528), /* NUMBER OF LINES / PAGE */ 
PAGELINE (®), /* NO. LINES ABOVE CURRENT */ 
HEADMARGN (16), /7* BLANK BEFORE HEAD */ 
TOPMARGN (48), /* BLANK BEFORE TEXT */ 
BOTMARGN (480), /* BLANK AFTER NORMAL TEXT */ 
FOOTMARGN (496), /* BLANK AFTER FOOT */ 

PAGENO (1), /* PAGE NUMBER */ 

PAGEFORM CEE) /* FORMAT FOR PAGE NO. */ 
SPACING (@), /* SPACING BETWEEN LINES */ 
VERSION (2), /* DOCUMENT VERSION NUMBER */ 
HashLevel (@), /* Hash Out Level */ 

Bar S$Char C'4y")y /* Revision Bar Character */ 
CmdsBar$Char ('|'), /* Revision Bar Character */ 
HashSsChar (2 8 )9 /* Hash Character */ 
Cmd$HashsChar ('/'), /7* Hash Character */ 

DropsChar ('.'), /* Character for Drop cmd */ 
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Appendix II: Defaults (continued) 


CMDFLAG ( 
LITERALFLAG  ( 
ULINEFLAG ( 
MACROFLAG ( 
DELIMFLAG ( 
NIBFLAG ( 


’ /* Macro Recognition Char */ 
’ /* Macro Argument Delimiter */ 
’ 7* Non-Trivial Blank Char */ 


AUTOIND (5), 
AUTOSKIP (1), 
AUTOTEST (2); 
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I. THE MACRO PROCESSOR LANGUAGE 


This document describes the syntax and semantics of the 
Macro Processor Language (MPL). 


A. INTRODUCTION 


1. GENERAL OPERATION 


Understanding MPL requires awareness of the basic algorithm 
used during its interpretation of textual input. The basic 
Operation performed in all macro processors is substitution 
in which macro function calls are replaced by their textual 
values. The processor reads a stream of characters 
consisting of text that has no meaning to the processor, 
interspersed with invocations of macro functions. The macro 
functions guide the process by which textual results are 
Substituted for macro calls. Thus the transformation to the 
string of characters passing from its input to its output 
stream. 


When the macro processor is in its Normal mode of reading 
text, the appearance of a distinguished character (the 
"Metacharacter"-- a "%" will be used in this document) in 
the input stream will be a signal that a macro processor 
function is to be invoked. The metacharacter is optionally 
followed by the calli-literally character, "*", which 
determines how the evaluation is to be performed. Next is 
the name of a built-in or user-defined macro function to be 
called. Next, arguments, if any, are identified and 
evaluated. Finally, the specified function will be 
performed and the text of the function call will be replaced 
by the textual value returned by the function. It should be 
noted that the value may be the null string, and that 
functions may have side effects. AS an example, _ the 
function DEFINE has the side effect of causing a macro to be 
defined. The value of DEFINE is always the null string. 


Generally, when the macro processor is in the Literal mode 
of reading text, the metacharacter is ignored - the text is 


25 


MPL 8986 SOFTWARE TOOLBOX, V1.1 


treated as literal characters. The exception to this rule 
is that the three "high priority" functions (Escape, 
Comment, and Parameter Substitution) are recognized in both 
Normal and Literal modes. 


For a more complete description, see the section entitled 
"The Macro Processor Scanning Algorithm." 


2. TERMINOLOGY AND CONVENTIONS 


For the purposes of illustration, a percent sign will be 
used as the Metacharacter throughout this document. The 
user may temporarily change the metacharacter by using the 
METACHAR function. 


The term “logical blank" refers to a blank, horizontal tab, 
carriage return, or linefeed character. 


Throughout the document the term "parameter" refers to what 
are sometimes known as "dummy parameters" or "formal 
parameters" while the term "argument" is reserved for what 
are sometimes known as "actual parameters". The terms 
"Normal" and "Literal", names for the two fundamental modes 
used by the macro processor in reading characters, will be 
capitalized in order to distinguish these words from their 
ordinary usage. 


This document uses a BNF style syntactic notation to specify 


the syntax of the macro processor language. Non-terminal 
syntactic types are represented by lower case words, 
sometimes containing the break character, " ". If a single 


production contains more than one instance of a syntactic 
type each instance may be followed by more than one unique 
integer so that the prose description may unambiguously 
refer to each occurrence. 


B. BASIC ELEMENTS OF THE MACRO LANGUAGE 


1. IDENTIFIERS 


With the exception of some builtin functions, all macro 
processor functions begin with an identifier, which names 
the function. Parameters also are represented by 
identifiers. A macro processor identifier has the following 
syntax: 


id = alphabetic | id id_continuation 
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The alphabetic characters include upper and lower case 
letters. An id_continuation character is an alphabetic 
character, a decimal digit, or the break character ("_"). 


Examples: WHILE Add_2 MORE_TO_DO Much More 


An identifier must not be split across the boundary of a 
macro and may not contain Literal characters. 


For example, 


"$¢(FQOG)" is illegal. The first metacharacter is 
followed by the letters "FOO", but they do not 
constitute an identifier since they are Literal 
characters. 


"SADD$SUFFIX", where SUFFIX is defined as "UP" is a 
call to ADD followed by a call to SUFFIX, rather 
than a call to ADDUP, because identifiers may not 
cross macro boundaries. 


A null-string bracket or escape function ( "%()" or "39" ) 
will also end an identifier, and since these functions have 
no textual value themselves, may be used as separators. 


Example: 


"STOMZO@SMITH" concatenates the value of the macro, 
TOM, to the string, "SMITH". 


This could also be done by writing, “TOM%(SMITH)". 


Upper and lower case letters are equivalent in their use in 
identifiers. ("CAY", "cat", and "cAt" are equivalent.) 


2. TEXT AND DELIMITERS 


"Text" is an undistinguished string of characters. It may 
or may not contain items of significance to the macro 
processor. In general, the MPL processor simply copies 
characters from its input to its output stream. This 
copying process continues until an instance of the 
metacharacter is encountered, whereupon the macro processor 
begins analyzing the text that follows. 


Each macro function has a calling pattern that must match 
the text in an actual macro function call. The pattern 
consists of text strings, which are the arguments’ to the 
function, and a number of delimiter strings. 


For example, "“LEFT( FIRST, SECOND )" might be a 
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pattern for a macro, LEFT, which takes two 
arguments. The first argument will correspond to 
the parameter, FIRST, and the second to the 
parameter, SECOND. The delimiters of this pattern 
are ae ee ey and a ae 


A text string corresponding to a parameter in the pattern 
must be balanced with respect to parentheses (see below). 
A delimiter which follows a parameter in the pattern will be 
used to mark the end of the argument in an actual call to 
the macro. 


An argument text string is recognized by finding the 
specific delimiter that the pattern indicates will end the 
string. A text string for a given argument consists of the 
characters between the delimiter (or macro identifier) that 
precedes the text and the delimiter which follows the text. 


In the case of built-in functions, there are sometimes 
additional requirements on the syntax of an argument. For 
example, the text of an argument might be required to 
conform to the syntax for a numeric expression. 


3. BALANCED TEXT 


Arguments must be balanced with respect to left and right 
parentheses in the usual manner of requiring that the string 
contain the same number of left and right parentheses and 
that at no point during a left to right scan may there have 
been more right parentheses than left parentheses. (An 
"unbalanced" parenthesis may be quoted with the escape 
function to make the text meet this requirement.) 


4. EXPRESSIONS 


Balanced text strings appearing in certain places in builtin 


macro processor functions are interpreted as numeric 
expressions: 
1. As arguments that control the execution of "IF", 


"WHILE", "REPEAT", and "SUBSTR" functions. 


2. As the argument to the evaluate function, 
"EVAL". 


Expressions are processed as follows: 
1. The text of the numeric expression will be 


expanded in the ordinary manner of evaluating an 
argument to a macro function. 
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2. The resulting string is evaluated to both a 
numeric and character representation of the 
expression. 


Operators (in order of precedence from high to low): 


Parenthesized Expressions 

HIGH LOW 

*» / MOD  SHL SHR 

+ = 

EQ LT LE GT GE NE 
NOT 

AND 

OR XOR 


Arithmetic: 


"17-bit signed" as used by the 8986 Assembler, ASM86 


C. INFORMAL DESCRIPTION OF MACRO PROCESSOR FUNCTIONS 


Enumerated below are the predefined functions that are built 
into the Macro Processor Language. Listed is the syntactic 
type name that will be used later to define the function, an 
example or schematic of typical usage, and a brief 
description of what the function does. A more complete 
description of each function is contained under separate 
headings of this document. 


Three functions, the comment function, the escape function, 
and the parameter substitution function, may be considered 
high priority functions because they are generally 
recognized and evaluated in both the Normal and Literal mode 
of reading text. The call-literally character may not 
appear on calls to these functions. 


comment function %'This is a comment'! 


The comment function allows the user to put comments into 
macro definitions. 


escape function B2(( 
The escape function is used to quote 9-9 characters (2 in 


the example) and prevent them from having their ordinary 
interpretation for the macro processor. 
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parameter substitution function SPARAMETER1 


The parameter substitution function is used inside a 
user-defined macro's body (its definition) to cause the 
substitution of an argument for a corresponding parameter. 
It is recognized everywhere except inside a comment or an 
escape. Macro parameters have exclusive scope, that is, 
they may be referenced within the body of the macro to which 
they belong, but not with macros that are called from within 
that body. 


The rest of the functions have no special priority. They 
are recognized when reading Normally and not recognized when 
reading Literally: 


bracket function 3(Some text) 


The bracket function is used to quote some text, i.e., 
prevent it from being evaluated (except for the comment, 
escape, and parameter substitution functions). It is always 
called Literally; the call-literally character is not 
allowed in the call. This builtin macro function effects a 
temporary change to the Literal mode from the Normal mode. 


evaluate function ZEVAL(12 + %factor * 7) 
The evaluate function evaluates text strings which represent 
numeric expressions. If the argument does not have the 
syntax of a numeric expression, then an error occurs. 


length function %LEN(ABDEF) 


The length function returns a character representation of 
the number equal to the length of its argument. 


equal function ZEQS(abc, abcd) 
greater than_function %GTS(abc, abcd) 
less_than_function %LTS(abc, abcd) 
not equal function %NES(abc, abcd) 
greater or equal function %GES(abc, abcd) 
less_or_equal_ function $LES(abc, abcd) 


These functions are used to compare two text strings, using 
the ordinary "dictionary" ordering of strings. The value is 
the character representation for minus’ one if the relation 
holds, or zero if it does not. 
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macro_def function %*DEFINE( MAC P; ) (...%P..-) 


The macro definition function allows the definition of 
macros which may or may not have parameters. The example 
shows a schematic definition of a macro, "MAC" with a single 
parameter, "P", delimited by the character, ";". 


macro _call_ function MAC This is an argument; 
The macro function call causes a previously defined macro to 


be called. 


conditional function %IF (%VAR EQ ©) THEN (...) 
ELSE Cena) FI 


repeat function $REPEAT (190) (...) 
while function SWHILE (%FLAG) (...) 
exit function S$EXIT 


These control functions are analogous to high level language 
statements of the same names, and have similar functions. 


in_function SIN 

out function %OUT (Message ) 
ci function SCI 

co_ function %$co(c) 


These functions support interactive macro processing by 
allowing I/O to the console. 


substr_ function %$SUBSTR(abcdef, 2,3) 

match function $MATCH(HEAD, TAIL) (a,b,c,d,e,f£,grh) 
These functions allow the user to extract subfields froma 
character string or scan a character string for an 
occurrence of a particular subfield. 

metachar_ function SMETACHAR( #) 


This function allows the user to change the character that 
is to be interpreted as the metacharacter. 
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D. THE MACRO PROCESSOR SCANNING ALGORITHM 


1. LITERAL OR NORMAL MODE OF EXPANSION 


At any given time the macro processor is reading text in one 
of two fundamental modes. When processing of the primary 
input file begins, the mode is Normal. Normal mode means 
that macro calls will be expanded, i.e., the metacharacter 
in the input will cause the following macro function to be 
executed. 


In the simplest possible terms, Literal mode means’ that 
characters are read Literally, i.e., the text is not 
examined for function calls. The text read in this mode is 
Similar to the text inside a quoted character string 
familiar to most users of high level languages; that is, the 
text is considered to be merely a sequence of characters 
having no semantic weight. There are important exceptions 
to this very simple view of the Literal mode. If the 
characters are being read froma user defined macro with 
parameters, the parameter references will be replaced with 
the corresponding argument values regardless of the mode. 
The Escape function and the Comment function will also be 
recognized in either mode. 


The mode can change when a macro is called. For 
user-defined macros, the presence or absence of the 
call-literally character following the metacharacter sets 
the mode for the reading of the macro's value. The 


arguments to a user defined macro are evaluated in the 
Normal mode but when the processor begins reading the 
macro's value, the mode changes to that indicated by the 
call. When the processor finishes reading the macro's 
definition, the mode reverts to what it was before the 
macro's processing began. 


To illustrate, suppose the parameterless macros, CAT and TOM 
are defined as follows: 


CAT is: “abcd %TOM efgh", and TOM is: "xyz" 
Now consider the text fragment, 
"J... DOG, %CAT, %*CAT, ELEPHANT, ..." 
Assume the string is being read in the Normal mode. The 
first call to CAT is recognized and called Normally. Since 
the new mode is still Normal, the definition of cCaT is 
examined for macro calls as it is read. Thus the characters 


"$TOM" in the definition for CAT are recognized as a macro 
call and again there is a new mode, again also Normal. The 
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definition for TOM is read, but it contains no macro calls. 
After the definition for TOM is processed, the mode reverts 
back to its value in reading CAT (Normal). After the 
definition of CAT is processed, the mode reverts back to its 
original value (Normal). At this point, immediately before 
processing the comma following the first call to CAT, the 
value of the text fragment processed thus far is: 


"... DOG, abcd xyz efgh" 


Now the processor continues reading Normally, finally 
encountering the second call to CAT, this time a Literal 
call. The mode changes to Literal as the definition of CAT 
is read. 


This time the characters from the definition are read 
Literally. When the end of the definition of CAT is reached 
the mode reverts to its original value (Normal) and 
processing continues. The value of the entire fragment is, 


"ll. DOG, abcd xyz efgh, abcd %TOM, efgh, ELEPHANT, Siar ns 


The use of the call-literally character on calls to builtin 
macro functions is discussed in the description of each 
function. The important thing to keep in mind when 
analyzing how a piece of text is going to be expanded is the 
environment in which it is read. 


2. THE CALL PATTERN 


In general, each macro function has a distinctive name which 
follows the metacharacter (and possibly the call-literally 
character). This name is usually an identifier, although a 
few built-in functions have other symbols for names. For 
identifier named functions, the macro processor allows the 
identifier to be the result of another macro call. 


For example, suppose the macro, NAME, has the value 
"BIGMAC" and the macro BIGMAC has the calling 
pattern, “BIGMAC X & Y¥;". Then the call, 


" 2. %$%NAME catsup & mustard; ..." 


is a call to the macro BIGMAC with the first 


argument having the value " catsup " and the second 
argument having the value " mustard". 


Associated with this name is, possibly, a pattern of 


delimiters and parameters which must be matched if the macro 
is to be syntactically correct. The pattern for each 
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builtin macro function is described in the section of this 
document dealing with that function. The pattern for a 
user-defined macro is defined at the time the macro is 
defined. 


At the time of a macro call, the matching of text to the 
pattern occurs by using the delimiters one at a time, left 
to right. When a delimiter is located, the next delimiter 
of the pattern becomes a new goal. The delimiters in the 
call are separated by either argument text (if there was a 
corresponding parameter in the macro's definition pattern), 
or by any number of logical blanks (in the case of adjacent 
delimiters in the pattern). Arguments are the balanced text 
strings between delimiters (or possibly between the macro 
identifier and the first delimiter). Null arguments are 
permitted. 


See the section "Macro Definition and Invocation" for more 
information on delimiters and their relationship to argument 
strings. 


3. EVALUATION OF ARGUMENTS - PARAMETER SUBSTITUTION 


MPL uses "call-by-immediate-value" as the ordinary scheme 
for argument evaluation. This means that as the text is 
being scanned for the delimiter which marks the end of an 
argument, any function calls will be evaluated as they are 
encountered. In order to be considered as a_ possible 
delimiter, characters must all be on the same level of macro 
nesting as the metacharacter which began the call. In other 
words, the arguments to a macro can be any mixture of 
plaintext and macro calls, but the delimiters of a call must 
be plaintext. 


For example, suppose STRG is defined as "dogs,cats" 
and MAC] is a macro with the calling pattern, 
"MAC1( Pl, P2)". Then in the call, 


"... MAC1( %STRG, mouse) ..." 


the first argument will be " dogs,cats" and the 
second argument will be " mouse". The comma in the 
middle of the first argument is not taken as the 
delimiter because it is on a different level than 
the metacharacter which began the call to MACl. 


When all arguments of a macro have been evaluated, the 
expansion of the body begins, with characters being read 
either Normally or Literally as discussed under "Literal or 
Normal Mode of Expansion". One should keep in mind that 
parameter substitution is a high priority function, i.e. 
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arguments will be substituted for parameters even if the 
macro has been called Literally. 


II. MACRO PROCESSOR FUNCTIONS 


A. THE EVALUATE FUNCTION 


The syntax for the Evaluate function is: 
evaluate function = "BVAL" "(" expr ")" 


The single argument is a text string which will be evaluated 
as an expression. The character string returned will be the 
value of the "EVAL" function. 


Examples: 
$EVAL(7) evaluates to "@7H" 
ZEVAL( (7+3)*2 ) evaluates to "14H" 


If NUM has the value "9191B" then 
SEVAL( %NUM - 5) evaluates to "99H" 


B. NUMERIC FUNCTIONS: LEN, EQS, GTS, LTS, NES, GES, and LES 
These functions take text string arguments and return some 
numeric information in the form of hexidecimal integers. 
length function = "LEN" "(" balanced text os Fas 


equal function = 
"EQS" "(" balanced text "," balanced text oe) 


greater _than_function = 
“6Ts" "(" balanced text "," balanced text a 


less_than_function = 
"LTS" "("  balanced_text "," balanced text ")" 


not_equal_ function = 
"NES" "(" balanced text "," balanced text aa Be 
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greater or equal function = 
"GES" "(" balanced_text "," balanced text ")" 


less_or_equal function = 
— "LES" "("  balanced_text "," balanced_text ")" 


The length numeric function returns an integer equal to the 
number of characters in the text string. The string 
comparison functions all return the character representation 
for minus one if the relation between the strings holds, or 
zero otherwise. These relations are for string compares. 
These functions should not be confused with the arithmetic 
compare operators that might appear in expressions. The 
ASCII code for each character is considered a binary number 
and represents the relative value of the character. 
"Dictionary" ordering is used: Strings differing first 
in their Nth character are ranked according to the Nth 
character. A string which is a prefix of another string is 
ranked lower than the longer string. 


C. THE BRACKET FUNCTION 


The bracket function is used to introduce literal strings 
into the text and to prevent the interpretation of functions 


contained therein. (Except the high priority functions: 
comment, escape, and parameter substitution. ) A 
call-literally character is not allowed; the function is 


always called Literally. 


bracket_function = bak aie balanced text oe 


The value of the function is the value of the text between 
the matching parentheses, evaluated Literally. The text 
must be balanced with respect to left and right parentheses. 
(An unbalanced left or right parenthesis may be quoted with 
the escape function.) Text inside the bracket function that 
would ordinarily be recognized as a function call is not 
recognized; thus, when an argument ina macro call is put 
inside a bracket function, the evaluation of the argument is 
delayed - it will be substituted as it appears in the call 
(but without the enclosing bracket function). 


The null string may be represented as %(). 


Examples: 
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%(This is a string.) 
evaluates to: 
"This is a string." 


%( %EVAL(10+5) ) 
evaluates to: 
" @EVAL(19+5) " 


D. THE ESCAPE FUNCTION 


The escape function provides an easy way to quote a few 
characters to prevent them from having their ordinary 
interpretation. Typical uses are to insert an "unbalanced" 
parenthesis into a balanced text string, or to quote the 
metacharacter. The syntax is: 


escape function = /* A single digit, @ through 9, followed 
by that many characters. */ 


The call literally character may not be present in the call. 
The escape function is a high priority function, that is one 
of the functions (the others are the comment function and 
parameter substitution) which are recognized in both Normal 
and Literal mode. 


Examples: 
"ll. $2%% ..." evaluates to "... %% ..." 


"... &(ab%l)cd) ..." evaluates to "... ab)cd ..." 


E. MACRO DEFINITION AND INVOCATION 


The macro definition function associates an identifier with 
a functional string. The macro may or may not have an 
associated pattern consisting of parameters and/or 
delimiters. Also optionally present are local symbols. The 
syntax for a macro definition is: 


macro def function = 
"DEFINE™ "(" macro id define pattern ")" [ "LOCAL" {id} J] 
"(" balanced text ")" 


The define pattern is a balanced string which is further 
analyzed by the macro processor as follows: 
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define pattern = 
{ (C{parm_id}] ({delimiter specifier}] } 


Gelimiter specifier = /*String not containing non-Literal 
id_continuation, logical blank, or 
"@" characters. */ 


“eu delimiter id 


The syntax for a macro invocation is as follows: 
macro call = macro id [ call_pattern Jj 


call_ pattern = /* Pattern of text and delimiters 
corresponding to the definition 
pattern. */ 


AS seen above, the macro id optionally may be defined to 
have a pattern, which consists of parameters and delimiters. 
The presence of this define pattern specifies how the 
arguments in the macro call will be recognized. Three kinds 
of delimiters may be specified in a define pattern. Literal 
and Identifier delimiters appear explicitly in the define 
pattern, while Implied Blank delimiters are implicit where a 
parameter in the define pattern is not followed by an 
explicit delimiter. Literal delimiters are the most common 
and typically include commas, parentheses, other punctuation 
marks, etc. Id delimiters are delimiters that look like and 
are recognized like identifiers. The presence of an Implied 
Blank delimiter means that the preceding argument is 
terminated by the first logical blank encountered. We will 
examine these various forms of delimiter in greater detail 
later in this description. 


Recognition of a macro name (which uniquely identifies a 
macro) is followed by the matching of the call pattern to 
the define pattern. It must be remembered that arguments 
are balanced strings, thus parentheses can be used to 
prevent an enclosed substring from being matched with a 
delimiter. The strings in the call pattern corresponding to 
the parameters in the define pattern become the values of 
those parameters. 


Reuse of the name for another definition at a later time 
will replace a previous definition. Built-in macro 
processor functions (as opposed to user-defined macros) may 
not be redefined. A macro may not be redefined during the 
evaluation of its own body. A parameter may not be 
redefined within the body of its macro. 
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Parameters appearing in the body of a macro definition (as 
parameter substitution functions) are preceded by the 
metacharacter. When the body is being expanded after a 
call, the parameter substitution function calls will be 
replaced by the value of the corresponding arguments. 


The evaluation of the balanced text that defines the body of 
the macro being defined is evaluated in the mode specified 
by the presence or absence of the call literally character 
on the call to DEFINE. If the DEFINE function is called 
Normally, the balanced text is evaluated in the Normal mode 
before it is stored as the macro's value. If the define 
function is called Literally, the balanced text is evaluated 
Literally before it is stored. a 


1. LITERAL DELIMITERS 


A Literal delimiter which contains id continuation 
characters, "@", or logical blanks must _ be quoted by a 
bracket function, escape function, or by being produced by a 
Literal call. Other literal delimiters need not be quoted 
in the define pattern. : 


Example 1: 
%*DEFINE ( SAY(ANIMAL,COLOR) ) (THE %ANIMAL IS %COLOR.) 
$SAY (HORSE, TAN) 

produces, 
THE HORSE IS TAN. 


Example 2: 
%DEPINE ( REVERSE [ Pl $%(.AND.) P2 ] ) ($P2 %P1) 
REVERSE [FIRST.AND.SECOND] 

produces, 
SECOND FIRST 


2. ID DELIMITERS 


Id delimiters are specified in the define pattern by using a 


delimiter specifier having the form, "@ id". The following 
example should make the distinction between literal and 
identifier delimiters clear. Consider two 
delimiter specifiers, "@(AND)" and "@AND " (the first a 


Literal delimiter and the second an_ Id delimiter), and the 
text string, 


"... GRAVEL, SAND AND CINDERS ..." 


Using the first delimiter specifier, the first "AND", 
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following the letter "S", would be recognized as the end of 
the argument. However, using the second delimiter 
specifier, only the second "AND" would match, because the 
second delimiter is recognized like an identifier. Another 
example: 


Definition: 
%S*DEFINE ( ADD Pl @TO P2 @STORE P3. ) 


( LDA $%Pl 
MOV B,A 
LDA %P2 
ADD B 
STA $%P3 


) 


Macro call: 
$ADD TOTAL1 TO TOTAL2 STORE GRAND. 


Generates: 
LDA TOTALI 


MOV B-A 
LDA TOTAL2 
ADD B 


STA GRAND 


3. IMPLIED BLANK DELIMITERS 


If a parameter is not followed by an explicit Literal or Id 
delimiter then there is an Implied Blank delimiter. A 
logical blank is implied as the terminator of the argument 
corresponding to the preceding parameter. In this case any 
logical blank in the actual argument must be literalized to 
prevent its being recognized as the end of the argument. In 
scanning for an argument having this kind of delimiter, 
leading non-literal logical blanks will be discarded and the 
first following non-literal logical blank will terminate the 
argument. 


Example: 
S*DEFINE ( SAY ANIMAL COLOR ) (THE %ANIMAL IS SCOLOR. ) 


The call, 
%SAY HORSE TAN 
will evaluate to, 
THE HORSE IS TAN. 


In designating delimiters for a macro one should keep in 
mind the text strings which are likely to appear as 
arguments. One might base the choice of delimiters for the 
define pattern on whether the arguments will be numeric, 
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strings of identifiers, or may contain imbedded blanks or 
punctuation marks. 


The LOCAL option can be used to designate identifiers that 
will be used within the scope of the macro for local macros. 
A reference to a LOCAL identifier of a macro occurring after 
the expansion of the text of the macro has begun and before 
the expansion of the macro is completed will be a reference 


to the definition of this local macro. Every time a macro 
having the LOCAL option is called, a new incarnation of the 
listed symbols is created. The local symbols’ thus have 


dynamic, inclusive scope. 


At the time of the call to a macro having locals, the local 
symbols are initialized to a string whose value is’ the 
symbol name concatenated with a unique number. The number 
is generated by incrementing a counter each time a local 
declaration is made. 


Definition: 
%*DEFINE (MAC] (FIRST,SECOND,THIRD)) LOCAL LABL 
(%LABL: LHLD %FIRST 


MOV AM 
LHLD %SECOND 
MOV BM 
LHLD S$THIRD 
MOV CM 


) 


Macro call: 
SMAC1(ITEM,NEXT, ANOTHER) 


Generates: (Typically, depending on value for local "LABL") 


LABL@3: LHLD ITEM 
MOV AM 
LHLD NEXT 
MOV BM 
LHLD ANOTHER 
MOV CM 


F. THE CONTROL FUNCTIONS: IF, REPEAT, and WHILE 


These functions can be used to alter the flow of control in 
a sense analogous to. that of their similarly named 
counterparts in procedural languages; however, they are 
different in that they may be used as value generating 
functions as well as control statements. 
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The three functions all have a "body" which is analogous to 
the defined value, or body, of a user-defined macro 
function. The syntax of these functions is: 


if function = "IF" "(" expr ")" "THEN" "(" body ")" 

[ "ELSE" on i body se a J a Oo 
repeat_function = "REPEAT" "“(" expr ")"  "(" body ")" 
while function = "WHILE" "(" expr ")"  "(" body ")" 


The expression will evaluate to binary numbers. As in PL/M, 
twos complement representation is used so that negative 
expressions will map into a large positive number. (e.g., 
"_1" maps into @FFFFH.) The bodies of these functions are 
balanced text strings, and although they look exactly like 
arguments in the syntax diagrams, they are processed very 
much like the bodies of user-defined macro functions; the 
bodies are "called" based upon some aspect of the expression 
in the IF, REPEAT, or WHILE function. The effects for each 
control function are described below. 


G. THE IF FUNCTION 


The first argument is evaluated Normally and interpreted as 
a numeric expression. 


If the value of the expression is odd (=TRUE) then the body 
of the THEN phrase is evaluated and becomes the value of the 
function. The body of the ELSE clause is not evaluated. 


If the value of the expression is even (=FALSE) and the ELSE 
clause is present, then the body of the ELSE phrase is 
evaluated and becomes the value of the function. The body 
of the THEN clause is not evaluated. 


Otherwise, the value is the null string. 


In the cases in which the body is evaluated, evaluation is 
Normal or Literal as determined by the presence or absence 
of the call-literally character on the IF. 


Examples: 


SIF (%VAL GT @) THEN( %DEFINE(SIGN)(1) ) 
ELSE( $DEFINE(SIGN)(@) ) FI 


If the value of the numeric symbol VAL is positive then the 
SIGN will be defined as "1"; otherwise, it will be defined 
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as "@". In either case, the value of the IF function is the 
null string. 


SDEFINE(SIGN) (%IF (%VAL GT @) THEN(1) ELSE(@) FI) 


This example has exactly the same effect as_ the previous 
one. 


H. THE REPEAT FUNCTION 


The REPEAT function causes its body to be expanded a 
predetermined number of times. The first argument is 
evaluated Normally and interpreted as a numeric expression. 
This expression, specifying the number of repetitions, is 
evaluated only once, before thé expansion of the text to be 
repeated begins. The body is then evaluated the indicated 
number of times, Normally or Literally, and the resulting 


string becomes the value of the function. A repetition 
number of zero yields the null string as the value of the 
REPEAT function call. 
Examples: 
Rotate the accumulator of the 8989 right six times: 

@REPEAT (6) 


( RRC 
) 


Generate a horizontal coordinate line to be used in plotting 
a curve ona line printer. The line is to be 191 characters 
long and is to be marked every 19 characters: 


SREPEAT (1) (+%REPEAT (9) (.))+ 
evaluates to: 


tb ove oie tected eiethie a hertlen'ePosecwe cewtvates  ((etes) a oteadsiee see 


I. THE WHILE FUNCTION 


The WHILE function tests a condition to determine whether 
the body is to be evaluated. The first argument is 
evaluated Normally and interpreted as a numeric expression. 
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If the expression is TRUE (=odd) then the body is evaluated, 
and after each evaluation, the condition is again tested. 
Reevaluation of the functional string continues until the 
condition fails (i.e., the value of the expression is an 
even number.) 


The body of the WHILE function is expanded Normally or 
Literally depending on how the function was called. 


Example: 


SWHILE ($I LT 16) ( ... 


SIF (%FLAG) THEN($DEFINE(I) (20)) FI 


se) 


J. THE EXIT FUNCTION 


The syntax for exit function is: 

exit function = "EXIT" 

This function causes termination of processing of the body 
of the most recently called REPEAT, WHILE, or user-defined 
macro. The value of the text already evaluated becomes the 
value of the function. The value of the exit function, 
itself, is the null string. 


Example: 
SWHILE (%Cond) ( ... 


SIF (%FLAG) THEN (%EXIT) FI 


K. CONSOLE INPUT AND OUTPUT 


The Macro Processor Language provides functions to allow 
macro time interaction with the user. 


The IN function allows the user to enter a String of 
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characters from the console. This string becomes the value 
of the function. The IN function will read one line from 
the console (including the terminating carriage return line 
feed). 


The OUT function allows a string to be output to the console 
output device. It has the null string as a value. Before 
it is written out, the string will be evaluated Normally or 
Literally as indicated by the mode of the call to OUT. 
The syntax of these two functions is: 
in_function = "IN" 
out function = "OUT" "(" balanced text ")" 
Examples: 

SOUT (Enter the date: ) 

%$DEFINE( DATE) (SIN) 


The CI function reads a single character from the cold start 
console. The character becomes the value of the function. 
CI does not echo the character. 


The CO function outputs a single character to the cold start 
console. It has the null string as a value. 


The syntax of these two functions is: 


ci_function = "CI" 
co_ function = "co" "(" char ")" 
Examples: 

%CO (A) 


%DEFINE(PASSWORD_CHAR) ( %CI) 


L. THE SUBSTRING FUNCTION 


The syntax of the substring function is: 


substr_ function = 
"SUBSTR" "(" balanced text "," exprl "," expr2 ")" 


The text string is evaluated Normally or Literally as 
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indicated by the mode of the call to SUBSTR. Assume the 
characters of the text string are consecutively numbered, 
starting with one. If expression ] is zero, or greater than 
the length of the text string, then the value of this 
function is the null string. Otherwise, the value of this 
function is the substring of the text string which begins at 
character number expression 1 of the text string and 
continues for expression 2 number of characters or to the 
end of the string (if the remaining length is less than 
expression 2). 


Examples: 
%SUBSTR (ABCDEFGH,3,4) has the value "CDEF" 


$SUBSTR (%(A,B,C,D,E,F,G)12,199) 
has the value ",B,C,D,E,F,G" 


M. THE MATCH FUNCTION 


The syntax of the match function is: 
match function = 
"MATCH" "(" idl delimiter specifier id2 wy 
. "(" balanced_text a 


The match function uses a pattern that is similar to the 


define pattern of the DEFINE function. It contains two 
identifiers, both of which are given new values as a result 
of the MATCH function, and a delimiter specifier. The 


delimiter specifier has the same syntax as that of the 
DEFINE function. The balanced text is evaluated Normally or 
Literally, as indicated by the call of MATCH, and_ then 
scanned for an occurrence of the delimiter. The algorithm 
used to find a match is exactly the same as_ that used to 
find the delimiter of an argument to a user-defined macro. 
If a match is found, then idl will be defined as the value 
of the characters of the text which precede the matched 
string and id2 will be defined as the value of the 
characters of the text which follow the matched string. If 
a match is not found, then idl will be defined as the value 
of the text string, and the id2 will be defined as the null 
string. The value of the MATCH function is always the null 
string. 


Examples: 


Assume XYZ has’ the value "19@,200,300,400,500". Then the 
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call, 
SMATCH(NEXT,XYZ) (%XYZ) 
results in NEXT having the value "190" and xyYZ having the 
value "290,309,498,590". 
$DEFINE (LIST) (FLD1,3E20H,FLD3) 


SWHILE (%LEN(%LIST) NE @) 


( SMATCH(PARM,LIST) ($LIST) 
LDA %PARM 
MOV M-A 
INX H 


) 


The above will generate the following code: 


LDA FLD1 

MOV M,A 

INX H 

LDA 3E20H 

MOV M,A . 
INX H 

LDA FLD3 

MOV M,A 

INX H 


Assume that SENTENCE has the value "The Cat is Fat." and 
that VERB has the value "is", then the call, 


SMATCH (FIRST $VERB LAST) (%SENTENCE) 


results in FIRST having the value "The Cat " and LAST having 
the value " Fat." 


N. THE COMMENT FUNCTION 


The comment function allows the programmer to comment his 
macro definition and/or source text without having’ the 
comments stored into the macro definitions. The 
call-literally character may not be present in the call to 


the comment function. The syntax is: 


comment function = "'" text ( "'" | linefeed ) 


When a comment function is recognized, text is 
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unconditionally skipped until either another apostrophe is 
recognized, or until a linefeed character is encountered. 
All text, including the terminating character, is discarded, 
i.e., the value of the function is always the null string. 
The comment is always recognized except inside an escape 
function. Notice that the comment function provides a way 
in which a programmer can spread out a macro definition on 
several lines for readability, and yet not include unwanted 
end-of-line characters in the called value of the macro. 


Examples: 
%' This comment fits within one line.' 


%' This comment continues through the end of the line. 


O. THE METACHAR FUNCTION 


The metachar function allows the programmer to change the 
character that will be recognized by the macro processor as 
the metachar. The use of this function requires extreme 
care. The value of the metachar function is the null 
string. The syntax is: 


metachar function = "METACHAR" "(" balanced text ")" 

The first character of the balanced text is taken to be the 
new value of the metachar. The following characters cannot 
be specified as metacharacters: a logical blank, left or 


right parentheses, an identifier character, an asterisk, or 
control characters (i.e., ASCII value < 2@H). 


III. USING THE MPL MACRO PROCESSOR 


A. FURTHER EXAMPLES 


The following is intended to provide some further examples 
and guidance to the user of the MPL processor. 


The MPL processor may be viewed as a general "toolbox" for 
doing textual processing. Before diving into a particular 
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application one would be well advised to develop a set of 
tools for the application at hand. A few examples will be 
examined. 


NOTE: the acronym ICAN used below refers to the INTEL 
8080 and 8948 assemblers, ASM89@ and ASM48. 


1. Variations on the DEFINE function 

A numeric assignment macro similar to ICAN's SET directive: 
%*DEFINE (SET A B) ( SDEFINE (%A) (SEVAL(%B)) ) 
Example: %SET NUMBER 12+(%VALUE-7) 

A macro to concatenate text to a macro time string variable: 
%*DEFINE (CAT A B) ( $DEFINE ($A) (%*%A%(%B)) ) 


Example: $%CAT LINE BUF %(some more chars for buffer) 


2. Modifying the Syntax of Other Built-in Macro Functions 


It should be obvious from the previous examples that by 
creating a user-defined macro one can in many cases replace 
a built-in function with a syntax more suited for the 
particular application or programming environment. 


3. Host Language Extensions 
A Conditional Repeat for PL/M: 


%*DEFINE (REPEATC BODY UNTIL EXPR;) LOCAL XXx 
(%XXX:DO; 
%BODY 
IF NOT( %EXPR ) THEN GOTO %XXX; 
END; 
) 


Example: %REPEATC 
body of the repeat 
UNTIL CHAR@='#' OR DONE; 


A Macro to Create "messages descriptors" for PL/M (address 
of character constant, followed by a comma, followed by 
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length.) 
%*DEFINE ( MSG(TEXT) ) (.('STEXT'),%LEN(%TEXT) ) 


Example: CALL SENDSMESSAGE( %MSG(Hello there.) ); 
expands to, CALL SENDSMESSAGE( .('Hello there.'),12 ); 


If it is possible that the argument to MSG could contain the 
metacharacter, one would substitute "%(%TEXT)" for "STEXxT" 
in the definition. 


B. ICAN TO MPL TRANSLATION 


The purpose of this section is to give some indication of 
how one might go about converting macros for the ICAN 
processor to those of the MPL processor. This is not 
intended to be an exhaustive treatment of the subject, but 
rather a guide to possibilities. 


ICAN directives will be considered one at a time, and the 
analogous MPL syntax will be given along with comments. 


1. Arguments 


Ordinarily, ICAN uses call-by-name for macro arguments, 
i.e., the literal text of the macro argument is substituted 
for the parameter in the body of the macro. 
Call-by-immediate-value can be forced by preceding the 
argument by a percent sign, forcing evaluation of the 
argument before substitution and expansion. MPL uses the 
exact reverse: call-by-immediate value is the ordinary case, 
but call-by-name can be achieved by enclosing the argument 
in the bracket function. In the majority of cases. the 
results are the same; however, it is possible that a 
user-defined macro in an argument might have different 
definitions at the point of call and the point of 
substitution. With this in mind the following 
transformations are suggested: 


ICAN MPL 
argument %(argument ) 
argument argument 


A workable rule might be to make the above transformations 
only if the argument contains macro calls. 
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2. Macro Definition and Call 
The transformation here is straightforward. 
ICAN: 


macro id MACRO Pl,P2,..Pn 
aa LOCAL Li 
LOCAL L2 
LOCAL Ln 
body 
ENDM 


MPL: 
%*DEFINE (P1,P2,...Pn) 


LOCAL Ll L2 ... Ln 
(body ) 


In transforming user-defined macro calls 


MPL 


and parameter 


references, the metacharacter must be placed in front of the 
identifiers and the transformation rule for arguments should 
be followed. Otherwise the call syntax is the same. 


3. SET Directive 


This is best handled by a user-defined macro 


similarly to ICAN's SET directive. 


that works 


%*DEFINE (SET ID VAL) ($DEFINE (%ID) (%EVAL(%VAL)) ) 


The transformation becomes: 
ICAN: 

name SET expression 
MPL: 


%SET name expression 


4. IF, ELSE, ENDIF Directives 
These transformations are very simple: 


ICAN: 
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IF expression or IF (expression) 

ELSE ENDIF 

ENDIF 

MPL: 

SIF expression or SIF (expression) 
THEN ( ... ) THEN ( ... ) 
ELSE ( ... ) FI 

FI 


5. REPT Directive 
Defining a macro similar to ICAN's REPT directive: 


%*DEFINE (REPT N BODY @ENDM ) 
( REPEAT ($N) 

( BODY 

) 
) 


The transformation becomes trivial: 
ICAN: 

REPT n 

ENDM 
MPL: 


SREPT n 


ENDM 


6. IRP Directive 
Defining a macro to operate similarly to IRP: 
%*DEFINE (IRP PARM,PLIST BODY @ENDM ) LOCAL LIST 
( SDEFINE (LIST) (PLIST) 
WHILE (%LEN($LIST) NE @) 


( SMATCH(%PARM,LIST) ($LIST) 
%BODY 
) 


) 
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ICAN: 


IRP dummy, <list> 


ENDM 
MPL: (with above user-defined macro) 


Z$IRP dummy,%(list) 


ENDM 


7. IRPC Directive 
Defining a macro to operate similarly to IRPC: ‘ 


3*DEFINE (IRPC PARM,TEXT BODY @ENDM ) LOCAL LIST 
( @DEFINE (LIST) (%(%TEXT) ) 
ZWHILE (%LEN(%*LIST) NE @) 
( SDEFINE (%PARM) 
(S*SUBSTR(%*LIST,1,1)) %'Pick off lst char.'! 
%DEFINE (LIST) 
(%*SUBSTR(%*LIST,2,9999)) %'Save the rest.'! 
%BODY 
) 
) 


ICAN: 
IRPC dummy, text 
ENDM 

MPL: (with above user-defined macro) 
$IRPC dummy, text 


ENDM 


8. EXITIM Directive 


The MPL EXIT macro may be substituted directly for the EXITM 
directive. 


ICAN MPL 


EXITM $EXIT 
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IV. STANDALONE MACRO PROCESSOR 


A. LINES 


A line is a string of characters up to and including a 


line-feed character. The maximum line length is 255 
characters. 


B. CONTROLS 


Control lines are any lines in the input plaintext whose 
first character is a "Ss". 


Note that there are no "primary" controls in the standalone 
version of MPL. Any control can occur anywhere in the file. 


SPRINT(filename) (abbreviated PR) 
This control causes the current listing file, if any, to 
be closed and "filename" to be opened as the new listing 
file. Default is :BB:. 


SLIST / SNOLIST (abbreviated LI/NOLI) 
Starts / stops the generation of listing to the current 
listing file. Default is LIST. 


SNOGEN (abbreviated NOGE) 
The listing file will include lines for the original 
source only. This is the default listing mode. 


SGENONLY (abbreviated GO) 
The listing file will include lines for the expanded text 
only. (Plain text in the original source file plus the 
values of the macros, but without the text of the macro 
calls.) 


SGEN (abbreviated GE) 

The listing file will contain a complete trace of ALL text 
processed by the macro processor. The value for a macro 
call will be listed on the line following and will be 
indented so that the first character of the value appears 
under the first character of the call. This option 
produces a very large listing, but if used selectively, it 
can be useful for debugging macros. 


SOBJECT(filename) (abbreviated oJ) 
This control causes the current OBJECT file to be closed 
and "filename" to be opened as the new OBJECT file. This 
file is the destination of the plaintext and the values 
generated by macro calls. Default is :CO:. 
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sout / SNOOUT 
These controls override the OBJECT control in the same way 
that LIST and NOLIST override the PRINT control. They can 
be used to unconditionally turn the flow of characters to 
the output file on and off. 


SINCLUDE(filename) (abbreviated IC) 
The console file (:CI:) may be included. Files (except 
the primary source file) may be included recursively. 


SSAVE / SRESTORE (abbreviated SA/RS) 
The current settings of the LIST/NOLIST, GEN/NOGEN/GENONLY 
and OUT/NOOUT switches are saved ona stack. The maximum 
nesting level of SAVES is eight. RESTORE resets’ the 
switches to the most recent SAVEd values. 


SSAVECI (filename ) 
If :CI: is used as the input file, the text typed in is 
written to the SAVECI file. This control causes’ the 
current save-console-input file, if any, to be closed and 
"filename" to be opened as the new save-console-input 
file. Default is :BB:. 


SEJECT / $TITLE (abbreviated EJ/TT) 
These controls are recognized as legal, but they are 
ignored. 


Cc. INVOCATION 
The invocation line for the standalone version looks like: 


MPL { input_file_ name {[ command_tail ] J 


If an input _file_ name is not specified in the invocation 
line, the current console input file will be used as the 
input file. The output file (OBJECT) is initially :Co:. 
The PRINT and SAVECI files are initially :BB:. 


The command tail is processed just like ordinary macro text 
before the input file is read. In essence, the command tail 
is read, and then "INCLUDEG" at the beginning of the primary 
source file. This is done by writing the command tail toa 
file called "MPL.TMP" on the same drive as MPL. Note that 
this does not meet the standard for the way command lines 
are processed, but has the advantage of allowing any text 
(including macros) to be used in the command tail. The 
command tail begins with the first non-blank character after 
the input file name and may be extended to multiple lines by 
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making "“&" the last character of all except the last line. 
Controls may be present in the command tail, however note 
that this necessitates making that first non-blank character 
a "S", otherwise the command tail will not be treated as a 
control line. 


Example invocations: 
MPL 
MPL :F2:INFILE.SRC 


?FI:MPL :F1:INFIL.SRC SOBJECT(:F1:INFIL.OBJ) PR(:F1:LST) & 
$SET(FLAG,1) & 
%DEFINE(FOO) (ABC...XYZ) & 
GENONLY 


D. PREDEFINED SET MACRO 


The SET macro is predefined, and may be used as discussed 
above. Note that the delimiter between the name and 
expression is a comma, not an implied blank. Also note that 
since SET is predefined, rather than builtin, the macro name 
SET may be redefined. 


The syntax looks like: 
%SET( name, expression ) 

This does exactly the same thing as: 
SDEFINE( name ) (%EVAL( expression )) 


E. NOTE ON CONSOLE INPUT USED AS INPUT FILE 


An end-of-file condition for console input can be simulated 
by the input line "EOF". That is, if the five characters 
"E","O0","E",<cr>,<lf£> are read as plaintext from console 
input, it is considered to be the end of that input file. 
(Note: the ISIS operating system allows control-z to 
indicate end-of-file from a keyboard input device.) 


F. MACRO ERROR MESSAGES AND RECOVERY 


The following is an updated list of macro error numbers with 
a suggested message. Extra text, passed by the macro 
processor, is indicated generically by a lower case 
description following the suggested message. For all of the 
following errors, the primary error message is followed by a 


56 


8086 SO 


trace 
and act 


199 


161 


192 


193 


104 


165 


196 


197 


188 


FTWARE TOOLBOX, V1.1 MPL 


back of the macro stack giving the nesting of pending 
ive macro calls and INCLUDE's. 


(64H) - UNDEFINED MACRO NAME 
The string following a metacharacter is nota 
valid macro in this context. The reference is 
ignored and processing continues with the 
character following the name. 


(65H) - ILLEGAL EXIT MACRO 
The built-in macro, "EXIT" is not valid in this 
context. The call is ignored. 


(66H) - FATAL SYSTEM ERROR 
Indicates loss of hardware and/or software 
integrity discovered by macro processor. 
MPL closes all files and aborts. 


(67H) - ILLEGAL EXPRESSION 
A numeric expression was required in a builtin 
macro function, but was ill formed. Abandon the 
call and continue processing with the character 
following the illegal expression. 


(68H) - MISSING "FI" 
The IF macro did not have a "FI" terminator. 
The IF macro is processed normally. 


(69H) MISSING "THEN" 
The IF macro did not have a "THEN" following the 
conditional expression clause. The call to IF 
is abandoned and processing continues at the 
point in the string at which the error was 
discovered. 


(6AH) - ILLEGAL ATTEMPT TO REDEFINE A MACRO: name 
Attempted to redefine a built-in, a parameter, 
or a user defined macro during its expansion. 


(6BH) - MISSING IDENTIFIER IN DEFINE PATTERN 
In a DEFINE, the occurrence of "@" indicated 
that an identifier type delimiter followed. It 
did not. The DEFINE is aborted and scanning 
continues from the point at which the error was 


detected. 

(6CH) - MISSING BALANCED STRING 
A balanced string, "( ... )" in acall toa 
built-in function is not present. The macro 


function call is aborted and scanning continues 
from the point at which the error was detected. 
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(6DH) - MISSING LIST ITEM 


In a builtin function, an item of a 
parenthesized list is missing. The macro 
function call is aborted and scanning continues 
from the point at which the error was detected. 


(6EH) - MISSING DELIMITER 


A delimiter required by the scanning of a user 

defined function is not present. The macro 
function call is aborted and scanning continues 
from the point at which the error was detected. 


(6FH) - PREMATURE EOF 


The end of the primary input file was read while 
the call to a macro was still being scanned. 


(70H) - DYNAMIC STORAGE (MACROS OR ARGUMENTS) 


OVERFLOW 
Either a macro argument is too long (possibly 
because of a missing delimiter) or not enough 
space is available because of the number and 
size of macro definitions. All pending and 
active macros and INCLUDE's are popped and 
scanning continues in the primary source file. 


(71H) - MACRO STACK OVERFLOW 


The macro context stack has overflowed. This 
stack is 64 deep and contains an entry for each 
of the following items: 


a. Every currently active input file (primary 
source plus currently nested INCLUDE's). 


b. Every pending macro call, that is, all calls 


to macros whose arguments are still being 
scanned. 


c. Every active macro call, that is, all macros 
whose values or bodies are currently being 
read. Included in this category are various 
temporary strings used during the expansion 
of some built-in macro functions. 


The cause of this error is excessive recursion 
in macro calls, expansions, or INCLUDE's. All 
pending and active macros and INCLUDE'sS are 
popped and scanning continues in the primary 
source file. 


114 (72H) - INPUT STACK OVERFLOW 
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Macro stack to save pointers to strings under 
analysis. The cause and recovery is the same as 
for Macro stack overflow. 


115 (73H) - (Continue Error) 
This error never occurs by itself. It is used 
to pass additional lines of explanatory text 
(Macro stack trace back) to the driver program 
after some other error has occurred. 


116 (74H) - LONG PATTERN 
An element of a pattern, an identifier or 
delimiter, is longer than 31 characters, or the 
total pattern is longer than 255 characters. 
The DEFINE is aborted and scanning continues 
from the point at which the error was detected. 


117 (75H) - ILLEGAL METACHARACTER: character 
The METACHAR builtin function has specified a 
character that cannot legally be used as a 
metacharacter: a blank, letter, numeral, left or 
right paren, or asterisk. The current 
metacharacter remains unchanged. 


118 (76H) - UNBALANCED ")" IN ARGUMENT TO USER DEFINED 
MACRO 
During the scan of a user defined macro_ the 
parenthesis count went negative indicating a 
unmatched right parenthesis. The macro function 
call is aborted and scanning continues from the 
point at which the error was detected. 


119 (77H) - ILLEGAL ASCENDING CALL 
A macro call beginning inside the body of a 
user-defined or builtin macro was incompletely 
contained inside that body, possibly because of 
a missing delimiter for the macro call. 


In addition to the above errors the following errors are 
detected in the dollar-sign control lines which are scanned 
by the macro processor: 


208 - BAD CONTROL PARAMETER 
201 - MULTIPLE INCLUDES ON ONE CONTROL LINE 
292 - NON IDENTIFIER FOUND IN PLACE OF CONTROL 


INVALID COMMAND: bad_command 
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| | 
| OMC 286 | 
| vl. | 
| | 


OMC286 will convert an object module conforming to the 
8486 object module formats to a valid linkable object 
module in the 88286 object module formats. Existing 8986 
programs or libraries, in which the source is not available 
or the user does not wish to look at the source, can be 
converted to linkable 89286 object modules, without 
recompilation of the source. Converted object modules can 
then be used as input to 89286 utilities, such as BND286, 
BLD286 and LIB286. 
Acceptable Input 


1) Output of 8986 translators, which do not contain 
absolute addresses. (e.g. AT(@Abs_ address) in PL/M86) 


2) Partially linked modules (output of Link86), which do 
not contain overlays or absolute addresses. 


3) Modules created by LINK86 using the BIND control. 


Unacceptable Input 
1) Libraries, except as specified below 
2) Modules containing overlays 
3) Modules which contain absolute addresses 
4) Output of Locs6 
5) Object modules containing interrupt procedures 


Any unacceptable input will cause a fatal error and OMC286 
Processing will be aborted. 


Invocation Command 


[E£device ]RUN] [device]omMCc286 inputfilename [controls] 


Inputfilename is the pathname of an 8986 object file. 
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controls: ERRORPRINT [(pathname)] | NOERRORPRINT 


OBJECT [(pathname)] | NOOBJECT 


Each of the OMC286 controls has an abbreviated form. If a 
keyword has the prefix 'NO' then the corresponding 
abbreviated form also has the prefix 'NO'. 


ERRORPRINT EP 
OBJECT OJ 


Default controls: NOERRORPRINT 
OBJECT (inputfilename.OMC) 


Controls 


If there are multiple specifications of the same control in 
the invocation command line then the last instance of that 
control will remain effective during the execution of the 
OMC286 utility. 


ERRORPRINT and NOERRORPRINT 


The ERRORPRINT control with a path name (e.g., 
"PRRORPRINT(:F1:PROG.ERR)") directs all the error messages 
(warnings, errors, and fatal errors) to the indicated file. 
The ERRORPRINT control without a path name (e.g., 
"ERRORPRINI") directs all the error messages to the default 
error print file ":co:". 


NOERRORPRINT control suppresses direction of error messages 
to the error print file. Fatal error messages will appear 
on the output console regardless of NOERRORPRINT. 
NOERRORPRINT is the default. 


OBJECT and NOOBJECT 


The OBJECT control designates the path name to which the 
output module is to be written. This file may not appear as 
the input file, and must be a file randomly accessible 
(e.g., a disk file). If the OBJECT control is not specified 
in the command tail, then OMC286 will generate an output 
object file which has the same name as the input object 
file, with the extension ".OMC". The specification of the 
OBJECT control without a path_name will also have the same 
result. 
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Example Invocation 
RUN OMC286 :F1:PROG.OBJ ERRORPRINT(:F1:PROG.ERR) 


This invocation creates the file :F1:PROG.OMC as the output 
file. All warnings and error messages are directed to the 
file :F1:PROG.ERR. 


Sign-on and Sign-off 


OMC286 will always sign on to the system console with the 
following message: 


system-id iAPX286 Object Module Converter, Vx.y 
Copyright 1983 Intel Corporation 


Completion of OMC286 processing will be indicated by a sign- 
off message sent to the system console. If there are no 
fatal errors OMC286 will sign-off as shown below: 


PROCESSING COMPLETE. n WARNINGS, m ERRORS 


The n and m represent the number of warning and nonfatal 
error conditions, respectively, encountered during 
processing. The ERRORPRINT control may be used to direct 
OMC286 to display warning and error messages at the console. 


If OMC286 encounters a fatal error condition, the sign-off 
message will be: 


PROCESSING ABORTED 


Fatal error messages are always displayed at the console. 


Usage of OMC286 


1) Output modules created by 8986 translators can be 
individually converted into 88286 OMFs and then used as 
input to any of the 89286 utilities. 

2) Multiple modules created by 8986 translators can first 
be prelinked using LINK86 with its NOBIND control. 
Then that output module may be converted to 88286 OMFs 
using OMC286. 

3) Output of Link86 under BIND control may be converted 
into an 8@286 OMF format. In this case, the converted 
output must be run through BND286, with no additional 
object modules and the LOAD control must also be used. 
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Examples of Usage of OMC286 


Assume there exists a program with 8886 object modules 
called MAIN.OBJ and UTIL.OBJ. There is also a file called 
MAIN.86, which is the result of: 


LINK86 MAIN.OBJ, UTIL-~OBJ TO MAIN.86 BIND 


Here are three ways the user can convert this program to a 
loadable 89286 program, corresponding to the three ways to 
use OMC286 above. 


1) RUN OMC286 MAIN.OBJ 
RUN OMC286 UTIL.OBJ 
RUN BND286 MAIN.OMC, UTIL.OMC 


2) RUN LINK86 MAIN.OBJ, UTIL.OBJ TO MAIN.LNK 
RUN OMC286 MAIN.LNK 
RUN BND286 MAIN.OMC 


3) RUN OMC286 MAIN.86 
RUN BND286 MAIN.OMC 


Converting 8886 Libraries 


Assume there exists an €@86 library called UTIL.LIB, that 
contains the two object modules UTIL1 MOD and UTIL2 MOD, to 
be converted to an 89286 library. If the names of the 
modules in the library to be converted are not known, use 
LIB86 with the LIST command to find out the names of the 
modules in the library. Next use LINK86 to separate each 
module from the library. 


RUN LINK86 UTIL.LIB( UTIL1 MOD ) TO UTIL1.86 
RUN LINK86 UTIL.LIB( UTIL2 MOD ) TO UTIL2.86 


Now use OMC286 to convert the 8986 object files. 


RUN OMC286 UTIL1.86 OBJECT(UTIL1. 286) 
RUN OMC286 UTIL2.86 OBJECT(UTIL2.286) 


Then use LIB286 to create an 8@286 library containing the 
modules UTIL1.286 and UTIL2.286. 


64 


8686 SOFTWARE TOOLBOX, V1.1 OMC 286 


DEBUG Information 


OMC286 will not convert any debug information existing in 
the input module to the output module. However, public and 
external symbols in the input module will be converted and 
transferred to the output module. These symbols will then 
be configured into debug information (89286 style) by the 
80286 utilities (since the output module created by _ the 
OMC286 will be an 8%286 style non-prelinked module). 


Problems Due to Invalid Code Sequences 


These problems occur due to some unique coding practices 
which are valid while executing on 8@86 but not on 8286. 
An examples of such code is loading a segment register 
(particularly the ES register, which is considered to be a 
"yolatile" register) with some invalid value. On 8@86, such 
practices are legal and are indeed used. However, on 88286, 
the processor will generate a hardware fault under such 
conditions. The OMC286 utility will not look at the code 
sequences in the input modules and will therefore be unable 
to detect such situations. Moreover, such situations may 
occur during execution over which no utility can have any 
control. The only way out of these situations is for the 
users to change the source appropriately so that’ the 
programs still work, but do not use any invalid code 
sequences. 


Similar cases may exist in programs using 8087 instructions 
and will have to be resolved by the users. Moreover, if 
programs containing floating point instructions are 
prelinked with the 8987-emulator library and then converted 
to the 89286 OMFs, then the output module may not be 
executable using the 8@287 processor. It is therefore 
advisable that, modules containing floating point 
instructions be converted to 89286 OMFs without prelinking 
with the 8987 emulator library. Note that, the OMC286 
utility will not attempt to detect whether an input module 
is a prelinked module or not. 


Fragmentation of Logical Segments 


Fragmentation of logical segments can occur only when the 
segments are part of a group. 


Note that if each individual module of 8@86 format is 


converted into an 88286 module separately, then in _ each 
conversion, the specific meaning associated with the input 
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segments such as "CONST", "CODE", "DATA" etc. will be lost 
in the output module. Therefore, when multiple converted 
modules are further "bound" by the 89286 utilities, each 
individual "CONST", "CODE" and "DATA" segment will be 
physically separated from the other, although they will 
still be part of the same segment, CODE or DATA (or 
whatever). This is only a cosmetic problem since references 
to symbols within each of these segments will be guaranteed 
to be equivalent to those in the input. The cosmetic 
problem may arise when the users try to disassemble some 
code which may be followed by a CONST portion. 


Support for Floating Point Instructions 


An 8886 program, using floating point, always contains a 
"wait" instruction before each floating point instruction; 
this wait instruction is not always needed in 89286. OMC286 
will leave them as they exist in the input module. This is 
not expected to cause any problems. 


Executable Segment Names 


The following is a list of segment names that become 
executable 89286 segments, when converted by OMC286. 


CODE 
* CODE /* "*" is any character string */ 
DCONCODE 

LIB_E87_PUB 

LIB_E87_INT 

LIB E87 INIT 

LIB E87 INTP 

LIB E87 INITP 

UTSCODE 

MQ CEL CODE 

DECODE CODE 

ENCODE CODE 

SIEVE_CODE 

NORMAL CODE 

LIB_87N_PUB 

LIB _87_NULL 

LIB 87 NULLP 

LIB_87_PUB 

LIB 87 INIT 

LIB_87_INITP 
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Cautions 
Converting Main Modules 


8086 compilers always create an STI instruction for main 
modules. STI is a privileged instruction on the 86286. Use 
the TASK PRIVILEGE control with BND286, in order to get the 
converted main module to run on the 89286. 


Programs already Linked with System Dependent Libraries 


Programs already linked with UDI, I/O libraries or system 
dependent libraries, may not run on an 89286-based system 
since these libraries may be different in the two 
environments. Therefore, these programs should be converted 
without these libraries. 


Programs Using Numeric Libraries 


8086 programs which use the 8987 emulator (E8987.LIB and 
E8087) cannot be converted as they are. Consequently, they 
must be modified to use the 8@87.LIB instead of the 
E8087.LIB and E8987. 8@86 programs which use 8@87.LIB must 
link in 8987.LIB before conversion. All public symbols 
should be purged (using LINK86's NOPUBLICS control) once the 
8087.LIB has been linked with the program to be converted. 
All other numeric libraries required by the program, must be 
80287 versions of the libraries in order for the converted 
program to run. 


PASCAL Programs 


8086 Pascal programs, using WRITE, WRITELN, READ or READLN 
will execute on 89286 if linked with 86286 pascal run-time 
libraries. REWRITE and RESE@® will work if the second 
parameter, to these procedures is also specified in the 
source. NEW and DISPOSE will work if the converted program 
is linked with 89286 Pascal run-time libraries. Programs 
using the default "Input/Output" scheme will not execute on 
the 86286 although they will be converted by OMC286 without 
any warnings and/or errors. When using BND286 to link the 
converted program, increase the LDTSIZE by at least 15. 


General: 


Programs containing interrupt procedures cannot be 
converted. 
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Public symbols on STACK segments are not supported on_ the 
80286. 


The method used to obtain stackpointer in ASM86 programs 
(i.e., defining a label beyond the segment limit) is invalid 
on 86286. BND286 will issue an error if it detects such 
programming practice. 


Warning and Error Messages 


SYSTEM INTERFACE ERROR 
error text 
FILE: pathname 


MEANING: A fatal error occurred in a call to the host 
operating system. The error text contains a message 
issued by the operating system. The pathname is present 
if the error is an I/O error. 


CAUSE: Such problems as an I/O error, or invalid 
parameters can cause this condition. 


EFFECT: OMC 286 processing is aborted and control 
returned to the operating system. 


ACTION: Correct the error and restart OMC286. 
ERROR 198: INPUT FILE MISSING 


MEANING: No input file name appeared on the invocation 
line. 


EFFECT: OMC 286 processing is aborted and control 
returned to the operating system. 


ERROR 191: PATHNAME TOO LONG 
NEAR: token string 


MEANING: This fatal error occurred because there are too 
many characters in a pathname in the invocation line near 
the token string. 


EFFECT: OMC 286 processing is aborted and _ control 
returned to the operating system. 


ACTION: Re-invoke OMC286 using a valid pathname. 
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ERROR 102: MISSING LEFT PARENTHESIS 
NEAR: token string 


MEANING: This fatal error occurred because a left 
parenthesis is missing after the token string. 


EFFECT: OMC286 processing is aborted and control 
returned to the operating system. 


ACTION: Insert a left parenthesis in the proper location 
and re-invoke OMC286. 


ERROR 193: MISSING RIGHT PARENTHESIS 
NEAR: token string 


MEANING: This fatal error occurred because a right 
parenthesis is missing after the token string. 


EFFECT: OMC 286 processing is aborted and control 
returned to the operating system. 


ACTION: Insert a right parenthesis in the proper 
location and re-invoke OMC286. 


ERROR 164: FILE ALREADY SPECIFIED IN COMMAND TAIL 
FILE: pathname 


MEANING: This fatal error occurred because the pathname 
exists in more than one place in the invocation line. 
One of the duplicate pathnames is explicit in or implied 
by the controls. 


EFFECT: OMC 286 processing is aborted and _ control 
returned to the operating system. 


ACTION: Re-invoke OMC286, ensuring that none of the 
pathnames, explicit or default, match. 


ERROR 195: INVALID DELIMITER IN COMMAND TAIL 
NEAR: token string 


MEANING: This fatal error occurred because the 
invocation line contained an improperly placed delimiter 
or used an illegal character as a delimiter. The invalid 
delimiter was detected either before or after the token 
string. 


EFFECT: OMC286 processing is aborted and control 
returned to the operating system. 


ACTION: Re-invoke OMC286 using valid delimiters in the 
invocation line. Valid delimiters include left and right 
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parentheses and commas. 


ERROR 107: UNKNOWN CONTROL IN COMMAND TAIL 
NEAR: token string 


MEANING: This fatal error occurred because one of the 
controls in the invocation line is invalid. The invalid 
control is contained in token string. 


EFFECT: OMC286 processing is aborted and control 
returned to the operating system. 


ERROR 198: SYNTAX ERROR 


MEANING: This fatal error occurred because the structure 
of the invocation line near token string is incorrect. 


EFFECT: OMC286 processing is aborted and control 
returned to the operating system. 


ERROR 189: CANNOT OPEN WORKFILE FOR SYMBOLS 


MEANING: This fatal error indicates that OMC286 cannot 
create a temporary file to use. 


EFFECT: OMC286 processing is aborted and control 
returned to the operating system. 


ACTION: Ensure all temporary files created by the 
operating system are deleted, then re-invoke OMC286. 


ERROR 119: NUMBER OF SYMBOLS EXCEEDS INTERNAL LIMIT 


MEANING: This fatal error occurred because the maximum 
number of symbols OMC286 can process has been exceeded. 


EFFECT: OMC 286 processing is aborted and _ control 
returned to the operating system. 


ERROR 111: NOT ENOUGH DISK SPACE FOR SYMBOLS 
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MEANING: This fatal error occurred because OMC286 does 
not have sufficient disk space to create internal data 
structures. 


EFFECT: OMC286 processing is aborted and control 
returned to the operating system. 


ACTION: Allocate files across disks in such a way that 
OMC286 has more space for temporary storage (refer to 
operating system documentation). 
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ERROR 112: INVALID OBJECT FILE 
FILE: pathname 
MODULE: module name 


MEANING: This fatal error indicates that the module 
name, contained in the file referred to by pathname, has 
an invalid format. 


EFFECT: OMC 286 processing is aborted and _ control 
returned to the operating system. 


ERROR 121: NOT AN OBJECT FILE 
FILE: pathname 


MEANING: The input filename on the invocation line does 
not contain an 8986 object file. The file could be a 
library file. 


EFFECT: OMC 286 processing is aborted and control 
returned to the operating system. 


ACTION: If the input file was an 8986 library file, the 
library can be converted by using OMC286 to convert each 
object file which makes up the library separately. Then 
use LIB286 to regenerate the library. 


ERROR 122: OBJECT FILE IS ABSOLUTE 
FILE: pathname 
MODULE: module name 


MEANING: Input file contains an 8986 object file which 
is absolute. This file is not acceptable input to 
OMC 286. 

EFFECT: OMC 286 processing is aborted and control 


returned to the operating system. 


ERROR 123: OBJECT FILE CONTAINS OVERLAYS 
FILE: pathname 
MODULE: module name 


MEANING: Input file contains overlay information. 
Probably the input file is the output of LINK86 using the 
OVERLAY control. This file is not acceptable input’ to 
OMC 286. 


EFFECT: OMC 286 processing is aborted and _ control 
returned to the operating system. 


ERROR 124: OBJECT FILE CONTAINS AN ILLEGAL RECORD 


FILE: pathname 
MODULE: module name 
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MEANING: Input object file contains a record that 
indicates that this file is not acceptable input to 
OMC286. The file could be an absolute file or ae file 
that contains an interrupt procedure. Neither is 
acceptable as an input file to OMC286. 


EFFECT: OMC286 processing is aborted and control 
returned to the operating system. 


WARNING 125: REGISTER INITIALIZATION FOR ES 
FILE: pathname 
MODULE: module name 


MEANING: Input object file contains register 
initialization for ES register. This information cannot 
be converted. 


EFFECT: OMC286 continues processing. Output module does 
not contain ES register initialization. 


WARNING 126: SYMBOL TABLE SPILLS TO SECONDARY STORAGE 


MEANING: This warning indicates that OMC286 is using 
disk space for symbol information, since available memory 
has already been used. 


EFFECT: OMC286 processing speed is reduced. 


ERROR 127: ILLEGAL ABSOLUTE SEGMENT 
FILE: pathname 
MODULE: module name 


MEANING: Input object file contains a segment which is 
absolute. File could be output of LOC86. 


EFFECT: OMC 286 processing is aborted and _ control 
returned to the operating system. 


ERROR 128: ILLEGAL ABSOLUTE RECORD 
FILE: pathname 
MODULE: module name 


MEANING: Input object file contains an absolute record. 
OMC286 will not process absolute files. 


EFFECT: OMC 286 processing is aborted and control 
returned to the operating system. 


ERROR 129: TYPE DESCRIPTION TOO LONG 
FILE: pathname 
MODULE: module name 
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MEANING: OMC286 encountered a type record that was too 
long to be processed by OMC286. 


EFFECT: OMC 286 processing is aborted and _ control 
returned to the operating system. 


ACTION: To convert this file, relink using LINK86 with 
the NOTYPE control. Then run the output of LINK86 
through OMC286. 


WARNING 130: SIZE OF GROUP EXCEEDS 64K 
GROUP: groupname 


MEANING: A group has been found whose component segments 
do not all lie within the 64K physical segment defined by 
the group base. 


EFFECT: OMC286 processing continues. When using BND286 
on the output of OMC286 addressing errors may result. 


ERROR 131: INVALID OVERLAPPING GROUPS 
SEGMENT: segment name 
GROUP: groupname 


MEANING: The same segment appears in more than one 
group. 


EFFECT: OMC 286 processing is aborted and _ control 
returned to the operating system. 


ERROR 132: ILLEGAL FIXUP 


FILE: pathname 
MODULE: module name 


MEANING: Input file contains a fixup which cannot’ be 
processed by OMC286. 


EFFECT: OMC 286 processing is aborted and control 
returned to the operating system. 


WARNING 133: EXTRA REGISTER INITIALIZATION INFORMATION 
IGNORED 


MEANING: Register initialization appeared more than once 
in the input file. 


EFFECT: OMC286 continues processing. OMC286 uses’ the 
first occurrence of the register initialization in the 
output file. 


WARNING 134: CS REGISTER NOT INITIALIZED 
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MEANING: No initialization for the CS register is found 
in the input file which is a main module. 


EFFECT: OMC286 continues processing. CS is initialized 
to zero. 


WARNING 135: SS REGISTER NOT INITIALIZED 


MEANING: No initialization for the SS register is found 
in the input file which is a main module. 


EFFECT: OMC286 continues processing. SS is initialized 
to zero. 


WARNING 136: DS REGISTER NOT INITIALIZED 


MEANING: No initialization for the DS register is found 
in the input file which is a main module. 


EFFECT: OMC286 continues processing. DS is initialized 
to zero. 


WARNING 137: CANNOT GENERATE STACK SEGMENT 


MEANING: An LTL input file contains a group called 
DGROUP, which contains a segment called STACK. OMC286 is 
unable to convert DGROUP into the two segments DATA and 
DATA with the STACK attribute, because the size of DGROUP 
is 64K. 


EFFECT: OMC286 continues processing. No STACK segment 
exists in the output file. 


ACTION: Relink the input file, using LINK86 with the 
SEGSIZE control, to reduce the size of the STACK segment. 


WARNING 138: SIZE OF MEMORY SEGMENT REDUCED 


MEANING: An LTL input file contains a group called 
DGROUP, which contains a segment called STACK. The size 
of DGROUP is 64K. OMC286 reduces the size of the memory 
segment in  DGROUP so that the 89286 segment called DATA 
with the STACK attribute can be created. This condition 
can occur for input files that were the result of LINK86 
BIND of input files using the SMALL or MEDIUM model of 
computation. 


EFFECT: OMC286 continues processing. Size of memory is 
reduced. 


WARNING 139: SIZE OF STACK REDUCED 
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MEANING: Input file contains a group called DGROUP, 
which contains a segment called STACK. If OMC286 created 
a segment DATA with the STACK attribute the size of the 
input STACK in DGROUP, the 89286 segments DATA plus DATA 
with the STACK attribute would be greater than 64K. 
OMC286 creates a smaller stack segment. This condition 
can occur for input files that were the result of LINK86 
BIND of input files using the SMALL or MEDIUM model of 
computation. 


EFFECT: OMC286 continues processing. Size of stack is 
reduced. 


WARNING 1490: SIZE OF MEMORY SEGMENT REDUCED ZERO 


MEANING: An LTL input file contains a group called 
DGROUP, which contains a segment called STACK. The size 
of DGROUP is 64K. The size of the STACK in DGROUP is 
greater than the size of MEMORY in DGROUP. OMC 286 
reduces the size of the memory segment in DGROUP to zero 
so that DATA STACK can be created. This condition can 
occur for input files that were the result of LINK86 BIND 
of input files using the SMALL or MEDIUM model of 
computation. 


EFFECT: OMC286 continues processing. Size of memory is 
reduced to zero. 


ACTION: If memory is needed to execute the program, 
relink the input file with LINK86, using the SEGSIZE 
control to decrease the size of the STACK segment. 


Conversion of Segmentation Models 


This section requires the knowledge and understanding of 
segmentation models. 


The users should be cautioned that programs which "mix" 
different segmentation models (e.g., SMALL and COMPACT) 
should be converted with proper understanding of how the 
segments will be placed after the conversion. In this case, 
the users may have to prelink some modules using LINK86 and 
then convert that output’ to 86286 OMFs. This is 
particularly true for the MEMORY segment in the 
SMALL/COMPACT/MEDIUM models. 


First of all, it must be noted that the segmentation model 
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as represented by the input object module must be deciphered 
so that a meaningful conversion to 89286 OMFs can be made. 
This is mainly due to the convention of the (DATA+STACK) 
combined segments and the absence of GROUPS in 88286 OMFs. 
This is necessary only in the case of SMALL and MEDIUM 
models. 


Conversion of DGROUP 


DGROUP gets converted to an 8286 segment called DATA. If 
DGROUP contains a segment called STACK, which is the case 
using the SMALL or MEDIUM segmentation models, another 89286 
segment is created. This segment is also called DATA but 
has the STACK attribute. 


Since the MEMORY segment will become part of the 88286 DATA 
segment, users of OMC286, which depend upon the memory 
segment to be at the top of memory as well as to be of non- 
zero length may have some problems. 


The following solutions can be used to solve this problem: 


o The users can ensure that the MEMORY segment will have 
enough size before it is converted by OMC286, thereby 
alleviating the problem caused by its indeterminate 
length at the time of execution. Users can ensure such 
size by prelinking the modules using LINK86 utility 
with its BIND and SEGSIZE control, or by writing an 
ASM86 module which does nothing but to specify the size 
of the MEMORY segment. If the user wishes to combine 
the output of OMC286 with other modules, an ASM86 
module, which specifies the size of the memory segment 
will have to be used. The memory segment size (set by 
the assembly language program) should be made as large 
as possible, especially LE the program being 
converted uses DqGetSize and .MEMORY to find the 
memory segment size. 


Example ASM86 program to set the memory segment size. 


name mem 
memory segment word memory 'memory' 
memsize db @F6@OH dup (?) 

memory ends 

end 


®F699H is the memory size in the example above. 
o If the user also requires that the MEMORY segment be at 


the top of the 89286 DATA segment (besides its being of 
some specific size) then the module containing the 
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nonzero length MEMORY segment should be specified as 
the last element in the input list to the 89286 
utilities (BND286 or BLD286). This is under. the 
assumption that the DGROUP of the corresponding 886 
module has the MEMORY segment at the top in the first 
place (this is the High Level Language's default). 


Conversion of DGROUP for LTL Modules 


In this case, the offsets of symbols and references to them 
have already been calculated by LINK86 and can not be 
changed. DGROUP gets converted to an 89286 segment called 
DATA. If DGROUP contains a segment called STACK, which is 
the case in SMALL and MEDIUM segmentation models, another 
89286 segment is created. This segment is also called DATA 
but has the STACK attribute. The segment called DATA with 
the STACK attribute will be created with the same size as 
the 8086 STACK segment in DGROUP if possible. The amount of 
space the 8886 STACK took in DGROUP becomes wasted space 
when DGROUP is converted. If the size of DGROUP plus the 
size of the STACK segment in DGROUP is greater than 64K, 
OMC286 makes some adjustments so that the two 89286 DATA 
segments created will not be greater than 64K. 


If the size of DGROUP plus the size of the STACK segment in 
DGROUP iS greater than 64K and the size of DGROUP is less 
than 64K, then the size of the 89286 STACK ( segment called 
DATA with the STACK attribute) will be less that the 8686 
STACK. OMC286 will generate a warning. 


If the size of DGROUP is exactly 64K, OMC286 creates the 
80286 STACK (segment called DATA with the STACK attribute) 
by reducing the size of the 8686 MEMORY segment. OMC 286 
will generate a warning that the size of memory is reduced. 


If the resulting size of the 86286 stack and memory area is 
not sufficient to make the program executable, run LINK86 
again on the input module to OMC286, using the SEGSIZE 
control to adjust the sizes of the segments STACK and 
MEMORY. 


Conversion of CGROUP 


An 8886 group named CGROUP will be converted to an 8G286 


segment called CODE. An 8@86 group named * CGROUP ( * means 
any name) will be converted to an 89286 segment called 
* CODE. 
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Conversion of Other 8986 Groups 


All other 8@86 groups will be converted to an 89286 segment 
with the same name as the 8986 group. If the group contains 
an executable segment then the group will be converted to an 
80286 segment with access type execute read; otherwise the 
group will be converted to an 88286 segment with access type 
read write. 


Conversion of 8986 Segments not Part of Groups 


8086 segments not part of groups will be converted to one 
80286 segment with the same segment name. Segments with the 
name CODE or * CODE will become executable 8%286 segments. 
All of the converted segments will have a privilege level of 
3. 
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E86287 is a software emulator for the 89287 numeric data 
processor. It is intended to serve environments which 
require floating point processing, but which lack the 89287 
NDP. Any iAPX-286 program that contains floating point 
operations may be executed on either an 86287 component or 
E89287. The following paragraphs describe the usage and 
characteristics of the emulator. 


Requirements 


The emulator must reside in memory with the floating point 
programs which use it. It occupies about 16 kbytes of 
memory, including: one data segment of 94 bytes and another 
of 2 bytes. A STACKSEG directive reserves 16% bytes of the 


system stack. The emulator has a conforming readable code 
segment which may be stored in ROM. The processor must 
operate in the protected virtual address mode while 
executing E89287. Programs which use E89287 must be located 
in readable code segments. Floating point instructions 
invoke £80287 by means of the iAPX-286's processor extension 
trap mechanism. Before any task uses the emulator, the 


processor extension trap must be initialized. 
Initialization 


The system which uses’ the 88287 emulator must execute an 
initialization procedure whenever a copy of E89287 is loaded 


to memory. The emulate processor extension control of the 
iAPX-286's machine status word must be set, and _ the 
emulator's entry point, "E89287", must be stored into the 
interrupt 7 descriptor of the IDT. An E8@287 software 


library has been included in the toolbox to assist with 
initialization. Both E89@287 and its library, E80287.LIB, 
should be bound to the task which performs initialization. 
A single call to the FAR procedure XQ INITE287 will set the 
machine status control and load the emulator trap pointer. 
Because it contains privileged instructions, XQ INITE287 
must execute at privilege level 6. A secon@ library 
procedure called xQ SET IDT may be used to set other entries 
in the interrupt deScriptor table, such as the floating 
point exception descriptor. Calls to this FAR procedure 
take the form of the following PL/M statement: 


CALL XQ_SET_IDT(IDT_ENTRY,GATE_DPL,PROC_PTR); 
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where IDT ENTRY is the interrupt number, GATE _DPL is the 
interrupt gate data privilege level, and PROC PTR points to 
the interrupt procedure. As long as the same copy of E8287 
remains at the same location, it need not be re-initialized 
and may be executed by tasks at any privilege level. 


Re-entrancy 


The 89287 emulator is designed to be completely re-entrant 
and easily multitasked. All temporary variables are stored 
in the current stack frame which is allocated and 
deallocated after every instruction trap. The context of 
the emulated 89287 is stored in the data segment A?MSR 
between floating point operations. As long as the contents 
of this data segment are preserved, any number of tasks may 
use E8@287 concurrently. The 89287 context may be switched 
in the conventional manner, using FSAVE and FRSTOR 
instructions, but there is an even faster method. The data 
segment A?MSRS contains’ the Single PUBLIC WORD PTR 
A?MSR SELECTOR. This variable defines the selector of the 
data Segment A?MSR for E8@287. All internal emulator 
references to A?MSR are made through A?MSR SELECTOR. If the 
selector is reassigned for each new task that uses E8G287, 
the context need not be saved and restored. All that is 
necessary is that a selector for a new 94-byte data segment 
be written to A?MSR SELECTOR, and the previous task's A?MSR 
selector be restored if that task is resumed. In this way, 
context switching can be made faster for the emulator than 
for the component. The contents of A?MSR are identical to 
the machine state stored with an FSAVE instruction, except 
that the stack registers are kept in a fixed order as though 
the top of stack pointer is always @. Data in A?MSR may be 
referenced through the PUBLIC WORD PTR A?MSR DATA. Knowing 
the format of segment A?MSR, the user may wish to manipulate 
the context of E89287 externally, without executing 
time-consuming floating point administrative instructions, 
but care must be taken to ensure that data is read from or 
written to the proper location. 


Differences 


There are a number of differences between the behavior of 
the 89287 and E89287 which are summarized as follows: 


Floating point exceptions are raised by E8@287, just as they 
are by the component. Whenever an unmasked floating point 
error is detected, the emulator executes an "INT 16" 
instruction and transfers control to the currently active 
floating point exception handler. unlike the 89287, E8%287 
calls the interrupt handler immediately upon termination of 
the the emulated instruction. Also unlike the 80287, the 
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emulator leaves its own return status on the system stack 
when branching to the error handler. The IP, CS, and FLAGS 
for the return from the floating point instruction are 
underneath the three words stacked for the emulator's 
return. If an exception handler must locate the original 
floating point instruction return, it can simply discard the 
emulator status, since this simply points to an "IRET" 
instruction within the emulator. 


FSETPM, FENI, and FDISI instructions are processed like FNOP 
by E89287. 


Certain condition flags in the 89287 status word are set or 
reset by the 88287 processor in an undocumented way, but are 
left alone by the emulator except for those operations which 
explicitly redefine them. 


Some transcendental instructions like FYL2X and F2XM1 may 
generate results for some operands which differ in the least 
significant bit for 88287 and E89287. These discrepancies 
are due to differences in the computational algorithms used 
by each floating point processor. 


Memory protection violations which occur as the result of 
emulated instruction memory operations may point back to 
emulator code. 


Related Publications 


For complete information on the 868287 numeric data 
processor, refer to the following manuals: 


- i1APX 286 Programmer's Reference Manual 
Numerics Supplement, 122164 


Timing 


This table lists typical execution times for selected 
floating point instructions on the specified numeric 
processors. E8987 is the 8087 emulator; 8887 is’ the 
hardware component; E87:87 is the ratio of E8987 to 8987 
execution time; SIM286 is the iAPX-286 simulator; E8287 is 
the 8287 emulator; 88287 is the hardware component; 
E287:287 is the ratio of E89287 to 89287 execution time. 
All timings have been normalized for a 5 mHz clock and are 
given in microseconds. 
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|E8087| 8087|E87:87|SIM286| £80287 |8@287|E287: 287 


INSTR\NDP |=====| ssse|ssses5|se=s5=5|seess=|=5555|=s=5==== 
nea. CRE EEE) ORRIN CRUE RMR, Oe ereeens (mene, | 
FNOP | 816| 1.1[ 736:1| 2146| 306| 2.5| 120:1 
eee a eee eh ee La 2 At 
FINIT | 866| 1.1| 727:1| 3586] 26@[  2.1| 124:1 
| | | | eee 
FSAVE |~1790|~65-6| 27:1|~8510|~ 400 |~45-3| 8:1 
| | | | | 
FRSTOR | 145@| 68.3[ 2i:1| ae ae ee 8:1 
| H Saees aoe 
FLD1 | 1966| 5.1] 208:1| 2490] 540| 8.4| 64:1 
| | | | | | 
FILD Dw | 2110|~11.8| 179:1| 399| 1400|~15.9|~ 68:1 


FILD DD | 2840| 14.5| 196:1| 4830@| 232@| 16-2|  143:1 


FILD DQ | 4846] 16.9] 286:1] 6530] 4170] 19.4] 215:1 


“FLD DD | 1336| 11.5] 116:1| 3119] 519| 12.9| 49:1 
Sars bo | s68 3 | ast | 3333] ass ass} ae 
Seer | s30 | tas |e | aga | sg ge | ae 
ssn — | rae esos | asta | as | ert] ee 
rps |te08| act | sagt| a3] | | a 
FRDD-SY7ST | “Weeo | “Wess [Tessa | 178/548 | as | ee 
TERE BE | 2858 |ao-3 | TreFT| awe! —TI96| Fa7| ET 


FDIV DD | 6440| 18.0| 358:1| 8830] 5320| 20.0]  266:1 


FSTP DT | 1350{ 12.2| Ill:1| 3930] 590| 12.7] 46:1 
| 


~FBSTP _|17976|104.8|-171:1| 21460|~12976|106-1] 122:1 
Saree 


| pi 
FPATAN |20156|114.3| 176:1| aoe eee 153:1 


| 
FXAM | 1600 


| | emer 
| 2.2| 454:1| 2330|  466|  3.3|  139:1 
| | | | | | enone 
~—FYL2X | 28050|181.4|~155:1|~31760| 18450|186.5| 99:1 
| | | | | | 
——¥F2xM1 | eis a 
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SPELL is a simple 8886 program used to check for spelling 
errors in the given text files. The program tokenizes the 
input into words and looks up each word in its dictionaries. 
If the word is not found, SPELL will query the user to find 
out if it is a misspelling, a word to be ignored or a 
correctly spelled word which is not in the dictionary. All 
words are converted to upper case for comparison. 


The main SPELL dictionary is maintained in a compressed form 
in the file SPELL.DC1l and must appear in the same directory 
as SPELL.86. A second word list file also used by the 
program for additional words is in the file SPELL.DC2 and 
must also be in the same directory. SPELL.DC2 is a simple 
ASCII file of words which are loaded into a_ secondary 
dictionary space for new words and user customization. This 
file may be edited by the user and is updated whenever a new 
correctly spelled word is encountered. 


Seven additional compressed dictionaries can also be used by 
SPELL. These have the names SPELL.DC3, SPELL.DC4, ... 
SPELL.DC8, SPELL.DC9. As with DCl and DC2, these must also 
be in the same directory. SPELL attempts to load these 
dictionaries in order, starting with DC3, then DcC4, etc. 
through DC9. AS soon as one of them is not found, SPELL 
stops the dictionary loading and does not attempt to load 
any of the subsequent dictionaries in the list. 


All the dictionaries must fit into memory. If memory is 
exhausted while loading any dictionaries after SPELL.DCl, 
SPELL informs the user and begins checking the input text. 


When an unknown word is found, SPELL will write out the line 
with the offending word and prompt the user with: 


"word", R)ight, W)rong, (Any)=ignore? 
where word is the string of letters under inspection. 
Typing an "R" will result in the word being saved and later 
written to the SPELL.DC2 file. Typing a "W" will result in 


an error line being written to a file with the same name as 
the input file but with extension "ERR". 
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The error line is of the form: 
LINE ###: "word" 


where ### is the number of the input file line with the 
offending word and "word" is as above. 


Typing any other character in response to the query will 
result in the word being ignored for the current execution. 


The invocation syntax is: 
SPELL option 
option = spell-option | dump-dict-option . 
spell-option = [ scribe-or-batch ] [ input-file-list ] . 


scribe-or-batch = scribe-option [ "BATCH" ] 
| "BATCH" [ scribe-option ] . 


scribe-option = "NOSCRIBE" | "SCRIBE" 
input-file-list = input_file [ input-file-list ] . 
dump-dict-option = "(" output file ")" 


The use of the SCRIBE switch indicates that all text between 
matching /'s is to be ignored and words immediately 
following a % are to be ignored. Also, the * literalizes 
the next character. The default is NOSCRIBE. (Refer to the 
description of SCRIPT in this manual.) 


The BATCH switch allows SPELL to be used in a completely 
non-interactive manner. Instead of prompting for a Right, 
Wrong, or Ignore response, SPELL considers all unknown words 
to be Wrong, and writes them to the appropriate 
input _file.ERR file. This allows, for instance, the 
spelling check to be executed ina submit file, with the 
assumption that the user verifies the incorrectness of the 
words at a later time. 


Notice that a list of input filenames may be processed. 
SPELL checks each file in the order given. 


If no input text filenames are given, then the program 
reverts to an interactive mode in which SPELL prompts for 
each line from the console and checks words. this is useful 
for entering variations of words previously entered. An 
escape character (1BH) entered in response to the prompt 
terminates the input. 
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The dump-dictionary option is used to consolidate the 
secondary dictionary SPELL.DC2 into the main dictionary, in 
compressed form. SPELL writes to the specified output file 
the total contents of its dictionaries, as a list of ASCII 
format words, one per line, in alphabetical order. This 
file can then be input to the WSORT program (see description 
following) to create a new SPELL.DCl. 


+HeeSeSSsSSS SSeS Sse SSSSeseSeaSssSsaet 
| | 
| WSORT | 
| vl.2 | 
| | 
Perse ts2 sss SSSeSSsSSeasSrssSesssassseszat+ 
WSORT converts a list of words into the compressed 


dictionary format used by the SPELL program. 


The input file MUST consist of a list of words, ONE WORD PER 
LINE. A line must end with a_ line-feed character. The 
first letter of a word must be the first character on the 
line; there can be no leading blanks or tabs. A word 
consists of upper and lower case alphabetic characters, 
"A"..."Z" and "a™..."z", and the apostrophe character, "'". 
(The apostrophe is also known as' the single quote; = 27H.) 
Lower case letters are converted to upper case. 


Since WSORT alphabetically sorts the list, the words in the 
input file may be in any order. 


WSORT can process a MAXIMUM of 3@99@ words. 
WSORT also limits the size of the compressed dictionary to 
6@@@@ characters. 


The invocation syntax is: 
WSORT infile [ "TO" outfile ] [ "vm" "(" vm-level ")" ] 


If "TO outfile" is not specified, then the output filename 
is the same as the input filename, but with extension "DCl". 
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The optional VM control allows the virtual memory size used 
by WSORT to be set to one of four values: 


vm-level virtual memory 
7) 128 KiloBytes 
1 256 KB 
2 512 KB 
3 1 MegaByte 


If vm-level is not in the range @ through 3, then vm-level 
reverts to the default value of 1, or 256 KB virtual memory. 


The size of virtual memory determines the maximum amount of 
Space that WSORT uses for storing the input records. If the 
physical memory available is less than the virtual memory, 
then WSORT spills records to disk (:WORK:) if necessary. 
However, if spilling takes place, the sort is likely to be 
extremely slow. 


USE RECOMMENDATIONS: 
1. Only sort files of size less than the amount of 
available physical memory. 


2. Set the virtual memory size to be as close to, but never 
less than, the size of the input file. 
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XREF produces an inter-module cross reference listing of 
symbols and numbers. The input to XREF is a_ set of list 
files, and the symbols are referenced to the line numbers in 


those files. 


The allowable input files are PL/M listings and ASM(86) 
listings. Any other input is treated as plain data and is 
not processed. 


The output format is: 
<symbol > <file name> <line #> <line #> ..... 
The symbols are listed in alphabetical (lexical) order. 


The characters following some of the line number references 
in the cross reference have the following meanings: 


vvvv 


symbol is set to a value at this line 

symbol is defined as an entry at this line 

symbol appears within a quoted string at this line 
symbol is defined at this line (EQU in asm) 


vO +N 
noua 
tou at 


XREF is invoked as: 
XREF input-list [ controls ] 


input-list is one or more filenames which are the 
list files to be cross-referenced. Filenames must 
be separated by commas. Wild card characters are 
allowed in the file specification. 


**k* CAUTION: use of wild card characters is only 
valid if the device referenced has 
an ISIS tormat file system. 


controls allowed are: 
PRINT (filename) 
Specifies the file where the output from the XREF 


program is placed. The default filename is 
:F1:XREFL.LST. If the file specified cannot be 
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opened then the default filename will be used on 
the workfiles drive. 


examples: PRINT(:F2:FN.XFR) 
Output goes to :f2:fn.xfr. 


PRINT(:F2:XY¥.LST) WORKFILES(:F3:) 
If, for some reason, :f£2:xy.l1st 
cannot be opened, :F3:XREFL.LST 
is used for the print file. 


EXCLUDING (symbol list) 


Specifies a list of symbols which are not to be 
included in the cross reference. The elements of 
the symbol list may be separated by commas or 


spaces. The list is terminated by the closing 
parenthesis. 
COMPRESS 


Specifies that the output is to be compressed by 
removing the blank line which normally separates 
each symbol in the output. 


TITLE ('title') 
Specifies a title that is printed at the top of 
each page of the output. The title string is a 
sequence of up to 6@ printable ASCII characters 
enclosed in quotes. 


NONUMBERS 


Specifies that numbers are NOT to be included in 


the cross reference output. If this control is 
not present then all numbers are cross-referenced 
along with all other symbols. Numbers appear in 


the output before symbols in lexical order. 


WORKFILES (:Fn:) 


Specifies the drive to contain the temporary files 
for XREF. The default is :Fl:. The temporary 
files have names "SOAnnn.TMP", where nnn is "609" 
for the first temporary file needed, and increases 
by one for each subsequent temporary file created. 


DOLLAR 


Specifies that the dollar ($) is to be considered 
a significant character in symbols and numbers. 


&8 
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The default is to consider all dollar signs as 


transparent and not to include them in symbol 
names. 


+S SS SS 555555555555 5555555555555 ==4 


| 
XREF8@ | 
v1.2 | 

| 


XREF8® is exactly like XREF, except that it processes ASM8@ 


or ASM48 assembly language listings, instead of ASM86 
listings. 
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PERF is a rather simplistic tool useful for determining the 
"hot spots" in a program's execution. It does this by 
partitioning memory into 1924 areas and sampling the program 
counter at a given rate to determine which area the program 
is executing in. At the end of the program or overlay, the 
count for each of the areas is displayed (only the non-zero 
ones). 


Invocation: 
PERF [ output file ] 


where output file is optional and may be used _ to 
direct the output of the tool toa different file. 
:CO: is used by default. 


PERF will then sign on and ask tor a command line. Type in 
the normal invocation line (without RUN). The filename of 
the program being analyzed is assumed to have the ".86" 
extension. PERF will then ask for the low and high offsets 
for the measurement and for the rate of sampling. the 
offset values should be the offsets in the code segment for 
the area of interest. For example, to monitor the entire 
CS-relative addressing space, use @ for the low offset and 
FFFF for the high offset. This implies that the entire 64K 
segment will be monitored with each area 64 bytes long. As 
smaller offsets are used, the areas will shrink accordingly. 
The RATE value is measured in milliseconds and represents 
the rate of the sampling. The default is one millisecond. 
For special cases, a tenth-millisecond rate can be generated 
by using FFFF for the rate. 


If the program has overlays, PERF will, at every load 
overlay call, flush the results of the just completed 
sample, display the name of the overlay, and ask for new 


range and rate values. If it desired to not sample a 
particular overlay, set both the low and high range offsets 
to zero. 


NOTE: This program will only monitor the starting CS 
segment, i.e. the CS value when the program is 
loaded. Therefore, it is not very useful for MEDIUM 
or LARGE case programs. It also will not work with 
LOCATEd programs since the initialization code is 
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built in a different segment. 
The output is: 
1111H -  hhhhhy nnnnH 


for each of the 1924 areas (as long as they're non-zero) 
where 1111H is the low end of the area, 
hhhhH is the high end of the area and 
nnnnH is the number of times the program counter 
was found to be in the area. 


Also provided is the ELAPSED TIME, which is the total 
number of samples which occurred, and the SAMPLE TIME 
which is the sum of the counts for the areas. 


This information is to be used with a link map to determine 
the locations that the program is spending its time. 


*** WARNING *** 


If the analyzed program has overlays, and if console input 
is set to transparent mode (with dq$special type 1 or 3) and 
not reset to line-edit mode (with dq$special type 2) before 
the next overlay call, then PERF may hang when prompting for 
the range information. 
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| | 
| GRAFIT | 
| v1.0 | 
| | 


GRAFIT is a simple tool that creates a graph version of the 
output of the PERF tool, to allow quick visual inspection 
for 'hot' spots in the code. 


GRAFIT is invoked as: 
GRAFIT input-file 


input-file MUST be the output _file generated by the PERF 
program. 


The output-file produced by GRAFIT has the same name as 
the input-file with extension 'GRF'. 


example. 
RUN GRAFIT :F5:TSTFIL.PRF 


writes to :F5:TSTFIL.GRF the graph version of the Perf 
output file :f£5:tstfil.prf. 


The output of GRAFIT is intended to be printed on a line 
printer, as the width of the graph produced extends toa 
full 132 columns. 


The following is an example GRAFIT output. Note that some 
of the lines actually extend farther right than is shown 
here. 


LOWER RANGE: 19099 

UPPER RANGE: 1406 

RATE: f£fff 

ELAPSED TIME: @9@2EA58H 
199@H - 19@1H ®Q25H *** 
1991H - 19@2H ®%909H 
19@92H - 1903H @@2BH **** 
1903H - 19@4H ©@1BH ** 
1995H - 1096H ®@@6H 
1997H - 1908H GBH * 
1998H - 19@9H @@45H *****x* 
1Q00AH - 109BH @@2FH **** 
19@CH - 190DH @@1AH ** 
1O@FH - 1010H @@36H ***** 
1913H - 1G14H QOB7H *KKRKKKKKKKKKKKKKE 
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1@15H 
1919H 
1@1DH 
1@1FH 
1922H 
16244 
1025H 
1@2CH 
16344 
1938H 
193CH 
1@3EH 
1@3FH 
1941H 
19444 
1@46H 
164BH 
194FH 
1@53H 
1954H 
1056H 
1@57H 
195948 
105BH 
1@5FH 
1663H 
1964H 
1@66H 
1968H 
1@6CH 
1@7FH 
1981H 
1983H 
1@85H 
1989H 
1@8CH 
1995H 
1999H 
1@ACH 
19AFH 
1@B3H 
1@B4H 
1@B5H 
1@BEH 
1@C9H 
1@CBH 
1@CDH 
1@CEH 
19@D2H 
16D6H 
1@E1H 


SAMPLE TIME: 
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1916H 90144 
191AH ®@2BH 
1@1EH 25H 
1920H 99OEH 
1@23H @9280H 
1@25H @O@1H 
1926H 9901H 
192DH 9@91H 
1935H 60@2H 
1939H 66@1H 
193DH 91H 
193FH 9001H 
1949H 6%0903H 
1942H 9634H 
1@45H G€O19H 
1847H ©@@2H 
1@4CH 9Q0AH 
1950H QO@AH 
1954H 9@07H 
1955H @®2B4H 
1957H ®@DFH 
1958H ®9@5AH 
195AH 69108H 
105CH 9@@3H 
1969H 6008H 
1964H 9@1FH 
1965H QOOF3H 
1967H 62@AH 
1969H 9%@C8H 
1@6DH %217H 
198@H %2C2H 
1@82H 91@5H 
1Q084H 6@62H 
1986H @9@2H 
128AH @1DH 
1@8DH 9@@3H 
1@96H @9@4H 
1@9AH @@1DH 
1@ADH S%9@BH 
1@BOH @G@G7H 
19B4H @92H 
19B5H Q®®DH 
19B6H 9%@91H 
1@BFH 9@15H 
1@CAH ®@D5H 
1@CCH @127H 
19CEH 6265H 
1@CFH 9@@4H 
1@D3H 91DAH 
1@D7H 6395H 
1ME2H @603H 

0090 2063H 
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pc is a simple floating-point Desk Calculator. DC supports 
a simple variable set, nested assignments, the four 
arithmetic operations addition, subtraction, multiplication, 
and division, plus exponentiation and the functions square 
root, exp, natural log, sine, cosine, and arctangent, and 
user defineable number base and width of decimal field. 


Input to DC is from the console keyboard; output is to the 
console screen. pc reads a line which contains an 


expression to be evaluated and writes the result on the next 
line, continuing in this manner until the eof line is read. 


INPUT SYNTAX 
input = statement-list . 
statement-list = statement [ statement-list. ] . 


statement = end-of-input-statement 
| expression end-of-line . 


end-of-input-statement = "#" end-of-line . 
end-of-line = [ ";" comment ] EOLN . 

EOLN = (* end-of-line character(s). *) 
expression = [ add-op ] term [ add-op term ]... 


add-op = "+" 


| term = power-factor [ mul-op power-factor ]... 


mul-op = "*" 
| ey Aa 
| power-factor = factor [ power-op factor ]... 
| power-op = "*" 
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factor = variable 

| number 

| "(" expression ")" 

| builtin "(" expression ")" . 
variable = id 


| assignment . 


id = id-char [ id-char ]... 


id-char = (* a single upper or lower case letter *) 
| the character "@" 
| the character "2?" . 
assignment = id "=" expression 
| id ":=" expression . 
number = fixed 
| string 
| float . 


fixed = digits {[ "." [ digits ] ] 
| { digits ] "." digits . 


digits = leading-digit [ digit ]... 


leading-digit = "go" | wy0 | nou | ugu | mq" 

| uo" | ne" | iy | ngu | "on 
digit = (* single character valid for current number base *) 
string = "'" [ sequence of characters ] "'" 


float = fixed(base 19) "E" [ add-op ] fixed(base 19) . 
builtin = "SORT" 

| "Exp" 

| "DN" 

| "SIN" 

| "cos" 

| “ARCTAN" 


IDENTIFIERS 


An identifier is any string of letters, where a letter is an 
upper or lower case alphabetic character "A" through "Z", or 
the at sign character "@", or the question mark "?". The 
lower case characters are equivalent to the upper case 
characters. If the identifier is not equal to one of the 
builtin functions, then only the first character of the 
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identifier is significant. Thus, DC supports a_ set of 28 
identifiers: "?", "@", "A"..."Z". 


SPECIAL IDENTIFIERS 


The identifier "@" represents the current numeric base used 
for input and output. The base may range from 2 through 36. 
In order to change base, "@" must be assigned the value of 
the base desired. The assignment to "@" is always made; 
however the base is changed only if the rounded value of "@" 
is in the correct range. 


The identifier "2?" represents both the format of the numeric 
result printed as output, and the number of fractional 
digits displayed (see the section OUTPUT below). The valid 
range of integers for controlling output is -18 through +18. 
The assignment to "?" is always made; however the output 
display format is changed only if the rounded value of "?" 
is in the correct range. 


Both "@" and "?" may appear in any context where an 
identifier is allowed. 


INITIAL VALUES OF VARIABLES 


The 26 alphabetic identifiers A through Z have initial 
values of zero. 

"@" is initialized to ten (decimal). 

"2" is initialized to +2. : 


FLOATING POINT INPUT 


Numbers input in floating-point representation are only 
valid if the base is ten. If the base is not ten and less 
than fifteen, an error is reported, since the digit "E" is 
not valid. If the base is fifteen or greater, the "E" is 
interpreted as a valid digit terminating the significand, 
rather than the beginning of the exponent part. For 
example, the input 1.1E+4 in base 16 is interpreted as 
(1.1E)+(4) with the result 5.1E (hex), instead of the 
desired result 11906. 


NON-DECIMAL INPUT 


It is noted that input numbers must’ start with a decimal 
digit, to avoid ambiguity with the variable ids. 
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ASSIGNMENTS 


Any number of assignments may appear anywhere in an 
expression. The assignment operators "=" and ":=" are 
equivalent. 


INPUT LINES 
The length of an input line is limited to 76 characters, 


including comments. A comment begins with an _  unquoted 
semicolon and terminates with the end of line. 


OUTPUT 

The numeric result of the expression is printed as output on 
the line following the input. intermediate results’ for 
embedded assignments are not displayed; the variables 


assigned must be entered individually on subsequent lines 
for displaying their values. 


If the value of the result is exactly zero, the single digit 
"9" is displayed. 


If "2?" is negative, then all output is displayed in 
floating-point representation. Floating-point output is 
always base ten, no matter what the "@" base is. The 
absolute value of "?" specifies the number of decimal digits 
displayed. 


If "?" is non-negative, then the value of the result 
determines the format of the output. If the absolute value 
of the result is greater than or equal to .99G@00000946566128 
and less than or equal to 2147483647 then the result is 
displayed in fixed-point representation. If the base is 
non-decimal, the base is displayed, in parentheses, 
following the result. If the absolute value of the result 
is not in the above range, the result is displayed in 
floating-point decimal representation. The absolute value 
of "?" specifies the number of fractional digits displayed, 
except in the case where the number of fractional digits 
plus the number of integral digits is greater than nineteen. 
In this case, the fractional part is truncated such that the 
total number of significant digits is nineteen. 


If the value of the result is positive infinity, a string of 
"+" is displayed; if the result value is negative infinity, 
a string of "-" is displayed; if the result value is a NAN, 
a string of "." is displayed. 
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SAMPLE SESSION 


run :fl:dc 
Desk Calculator (DC), V1.1 
Copyright 1983 Intel Corp. 
© ; NOTE THAT INPUT IS ON THE INDENTED LINES 
® 
13) ; AND OUTPUT IS ON THE NON-INDENTED LINES 
(5) 
2=18 sset maximum decimal places 
18 .PGGOGGOOGHGOBOGOGHGOHS 
ae). TELL. 
1.111111111111111119 
b=a*at*ta*a*a*a*ta*a*at*a 
2.867971999792441 286 
c=l1/b 
©. 34867844G190999003 
d=2147483647 ;maximum output integer 
2147483647 . QOOGOGBOD 
d+1 ;Sshould print as floating-point 
2.147483648999GGHOD0E+O8909 
e=1/a ;minimum output integer 
®.9GOGOGOHOGHH465661288 
1/(d+1) sfloating-point output 
4.656612873077392589E-G019 
Z=19*9*8*7*6*(y:=5*4)*3*2 ;shows value of z only 
3628899. DD2DOPGHGOOOHOD 
y ;y should equal 29 
20. POGODOGOPGODGLSBOD 


@=32 ;set base to 32 
1B. GOGOOHOGHGOGGOGHHH (32) 
d sbase 32 appears in parens 


IVVVVVV.@290@09800 (32) 
e 


Q@.DOOGDOGBOOHOBOHGHH (32) 


@=a 7set base back to 1¢ 
1D. QDODOPOOHGHOOHOOG 

?=) ;one decimal place 
1.0 

c 
®.3 

2?=9 snine decimal places 


9. QQOVGHDOO 
c 
®.348678446 
?=18 
18 . GGOGOG99GOHOHDOGO 
gq=l.le+4 sfloating-point input 
11999. QYGOOHWPHOPBHOOGD 
r=l.le-4 
Q.ODH11GDOHOGHGOHOHHO 
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DC 
@=16 
19. DBOHOHDOHHOGDHGHOOHOD 
s=].le+4 
5. 1LEQQOOGOODDSOHOOHOHOD 
t=l.le-4 
-2.E2QG@OQGOBODODDOOGDD 
@=Ga 


10. 9ODGDODOOOGOOOGHLDOOOH 
s 
5.117187509090000000 


t 
~2.8828125 20209009009 
?=-12 


-1.2Q20O99GDOO0GOGE+OOH1 

a 

1.111111111111E+9999 
b 

2.867971990792E+9999 
c 

3.486784401090E-B001 
d 

2.147483647090E+9 999 
e 

4.656612875246E-0G10 
¥ 

2. DDDDOPHOOHOGVE+O001 
z 

3.6288 G2GOOOGOE+9 O06 
?=18 

18. QLGGPOPOHWGHGHHOOOD 
pi=arctan(])*4 

3.141592653589793238 
cos(p*2) 

1. GBCGWOLHOOGHOPDHBGGOGOGD 
sin(p*2) — 

© 
cosine*] 

Q.348678440199966903 
pi*le5 

314159. 2653589793239 
272727272 

65536. D9DGBDGDDOOHOGHOD 
10°10*18°18° 18 
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(16) 
stry it in hex 
(16) 


(16) 


;Ssubsequent output is 


;floating-point for all values 


sallow fixed-point output 
sapproximate pi 


sid "pi" is variable "p" 


;should be c=€.34867... 
;only 19 significant digits 
;powers 


;positive infinity 


FEEEEEAEEEEEEEEEEDEEE EEE EET 


-19°199°199 
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snegative infinity 


;NAN 


sexit 
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pc87 is exactly like DC except that it uses the 8887 
hardware instead of the 8487 emulator. If an 8087 is 
present in the system, then DC87 can be used for faster 
results. 
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The program FUNC reads in a text file and creates a FUNCtion 
keymap from it for the Series IIIE. The invocation should 
look like this: 


[ RUN } Func [ <file-name> | RESET ] 


If a file name is specified, that file will be read in as 
the keymap file. If the RESET command is used, the FUNCtion 
keys will be reset to the values provided on system reset. 
If no file name or command is provided, the file FUNC.DEF 
will be read in as the keymap file. FUNC.DEF must reside on 
the same disk as FUNC.86. 


Here is an example of a function definition file: (do not 
use dashes) 


A run aedit 
Cc r calc 


E exit 
P pscope ws(32768) db(16) 


QWERTY 


The first character of a line must be the key to be defined. 
A blank space follows. The next N (< 255) characters is the 
text that will be inserted when FUNC+<key> is typed. All 


characters up to the CR,LF will be included. For example, 
in the 'A' definition above, there is a_ blank space after 
‘aedit' so that a file name can be entered. 


If the key to be defined is an upper case letter, the 
definition will be inserted for both upper and lower case 
versions of this function key. Thus, in the 'Q' definition 
above, both func-'Q' and func-—'q' are defined as 'QWERTY'; 
the following 'q' definition redefines func-'q' as 'qual'. 
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Func-'Q' retains the 'QWERTY' definition. The 'z! 
definition defines only func-'z' as 'zing', func-'Z' retains 
its previous definition, if any. The following '2Z! 


definition both defines func-'Z' and redefines func-'z' as 
'ZOoOo'. 


To allow a carriage return to be inserted as part of the 
function text, place a second CR,LF pair after the 
definition as in 'C', 'E', and 'P' above. Multiple line 
definitions are not allowed. 


The total number of characters in all definitions may not 
exceed 890. 


Function definitions are not additive so calling FUNC twice 
in a row may not have the desired effect, however, all 
default (IOC provided) function keys that are not redefined 
will remain in effect. 
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a 
| | 
| ESORT | 
| vl.l | 
| | 
SSR SSS SSSSSSSSSsSssS SSS esses eS SST HSH} 
ESORT sorts arbitrarily large files, using a partial sort 


and merge technique. It can sort by multi-keys (fields of 
columns), and allows record lengths up to 5118 characters. 
It also allows continuation lines within single records. 


A line in the input file is a string of characters up to and 
including a CRLF, a carriage-return,line-feed pair. 

ESORT is invoked as: 

ESORT <input-file> [ TO <output-file> ] [ <up-down> ] 


[ cc ( '<continuation-character>' ) ] 
{ F[IELD] ( <rangel> [ , <range2> [ ,..., <rangel@> ] ] ) ] 


Where 
<input-file> is the file to be sorted 
<output-file> is the sorted file 


<up-down> 
is either UP or DOWN, and means the output file 
should be ordered in ascending or descending order 


<continuation-character> 
is a printable character (ASCII code 2@H to 7EH) 
that will cause each line that begins with this 
character to be sorted with the last line previous 
that does not begin with this character. For 


example if the continuation character is an asterisk 
then: 

linel 

*line2 

*line3 

--eline 4 

*line 5 
will be treated as two sortable units (or records), 
the first beginning with linel and the’ second 


beginning with ...line 4. The CRLF and_ the 
continuation character are counted as part of the 
record, 
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<range> 
is Ni:Nj specifying a sort field starting at column 
Ni and going to column Nj. (Ni must be less than or 
equal to Nj). 


Defaults: 

output file <input-file>.SRT 

up-down UP (i.e. ascending order) 
continuation character none 

field l. If nothing is specified then 


there is one sort field: column 1 to 
the end of the record. 

2. If the <range> is a single number 
N then that sort field starts at 
column WN and goes to the end of the 
record. 


Note that to use a single column as the sort field, the 
column number must be entered twice. For example, 
FIELD(...,3:3,---) Will use only column three for this sort 
field. The precedence of the sort fields is the same as 
their order of entry. 


The first column of a record is numbered as column 1. 
An overlapping of the fields is permitted. 


In case that a record does not contain part of a key or the 
whole key, it is declared to be less then a compared record 
that contains that key (it is treated as if it is expanded 
by nulls). 


Error Messages 


SYNTAX ERROR 
an illegal control or illegal delimiter 


TOO, MANY ARGUMENTS 
more than 1@ fields were entered 


WRONG RANGE 
the last range read is illegal, the last column of 
the field is less than its first column, or _ the 
column is zero or larger than 5118 
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ILLEGAL CONTINUATION CHARACTER 
the continuation character is null or is longer than 
one character 


RECORD TOO LONG 
the program contains a record larger than 5118 bytes 
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HSORT is a simple 8886 program used to sort the lines of a 
file into ASCII lexical order. HSORT uses the "heap sort" 
method. 


A "line" in the file to be sorted is defined as a string of 
characters up to and including a line feed character. The 
maximum line length is 256 characters. If a line is longer 
than 256 characters, the first 256, or multiple of 256, 
characters are ignored, and the remaining characters on the 
line are sorted. 


All characters on a line are significant, including 
unprintable ASCII characters. 


HSORT does NOT allow multiple field sorting. Each line is 
considered to be a single field, starting with the first 
character on the line. 
HSORT allows a maximum of about 39900 lines. 
HSORT is invoked as: 

HSORT infile [ "TO" outfile ] [ "vm" "(" vm-level ")" J 
If "TO outfile" is not specified, the output is written toa 


file with the same name as infile, but with extension "SRT". 


The optional VM control allows the virtual memory size used 
by HSORT to be set to one of four values: 


vm-level virtual memory 
is) 128 KiloBytes 
1 256 KB 
2 512 KB 
5 1 MegaByte 


If vm-level is not in the range @ through 3, then vm-level 
reverts to the default value of 1, or 256 KB virtual memory. 


The size of virtual memory determines the maximum amount of 
Space that HSORT uses for storing the input records. If the 
physical memory available is less than the virtual memory, 
then HSORT spills records to disk (:WORK:) if necessary. 


109 


HSORT 8986 SOFTWARE TOOLBOX, V1.1 


However, if spilling takes place, the sort is likely to be 
extremely slow. 


USE RECOMMENDATIONS: 


1. Only sort files of size less than the amount of 
available physical memory. 

2. Set the virtual memory size to be as close to, but never 
less than, the size of the input file. 


If it is desired to sort files larger than the size of 


available memory, or to do multiple field sorts, then use 
ESORT, which is described elsewhere in this manual. 
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v1.3 


I. INTRODUCTION 
A. PURPOSE 


PASSIF was developed to automate the software testing 
process. 


Such testing involves (among other things) searching 
files for specific strings, or the lack thereof, checking 
whether two files (usually object modules) are identical, 
and checking whether specified files exist. 


In the past, performing and checking this style of test 
required the use of many different tools and utilities, and 
the examination and processing of huge disk files. 


PASSIF obviates this by directly performing the test- 
checking functions needed, and reporting the results ina 
processed and compact form. 


B. PHILOSOPHY 


It is intended that PASSIF be able to adequately process 
the great majority of test cases encountered in a normal 
test suite. It is not intended to handle all conceivable 
requirements of this style of software testing. 


It is assumed that PASSIF will typically be used _ to 
quality assure a large test base, run as a night job. 
PASSIF, therefore, is not a performance crucial program but 
its speed should be adequate for occasional interactive use. 


Under exceptional conditions, PASSIF will attempt’ to 
continue processing, if there is reasonable method of doing 
so. 


The design of PASSIF emphasizes simplicity and 
maintainability. 


C. EXECUTION ENVIRONMENT 


PASSIF runs in an 8%86-based UDI-compatible environment, 
specifically Series-III and Series-IV. 
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II. SPECIFICATION 
A. GENERAL METHOD OF OPERATION 
1. Overview 


PASSIF ascertains what assertion to check by reading its 
command tail. PASSIF then performs whatever functions are 
necessary to check the verity of the assertion. 


The results of the assertion checking are then reported 
ina disk file called ":fl:report.log". This file has a 
"banner" at the top with three decimal ascii numbers, 
representing tests executed, tests passed, and tests failed, 
respectively. The numbers are updated by PASSIF during each 
of its invocations. 


The report file is always opened in update mode. If the 
assertion(s) are true, then PASSIF merely increments’ the 
"TESTS PASSED" number and the "TESTS EXECUTED" number. 


If the assertion is false, then the "TESTS EXECUTED" and 
"TESTS FAILED" numbers are incremented, and a "failed 
assertion entry" for the test which failed, is appended to 
the end of the report file. A sample of a typical report 
file, and a detailed description of what type of information 
appears in a "failed assertion entry" appears below. 


Each time it is invoked, PASSIF dumps some test status 
information to the cold boot console. As soon as it comes 
up, it prints a carriage-return (but no line-feed). When 
PASSIF is finished processing, it prints out the new banner 
it has generated, but leaves off the carriage-return line- 
feed at the end. 


Thus, the user sees a periodically updated display of 
test status information on his console. He knows, in real 
time, when PASSIF is running (cursor at the beginning of the 
line), and when the rest of the test suite is running 
(cursor at the end of the line). The display of this 
information only costs one line of screen, which is painted 
over and over again, so the user won't lose status 
information which any other of his programs may have dumped 
to the console. 
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EXAMPLE OF A TYPICAL REPORT FILE 


13517 TESTS EXECUTED 13499 TESTS PASSED 00018 TESTS FAILED 


test 99533 failed 
PASSIF.86 STRING FOUND(ERROR 28)IN FILE(:F1:DC.MP1) 


test @9534 failed 
- PASSIF. 86 STRING FOUND(ERROR 29)IN FILE(:F1:DC.MP1) 


test 99714 failed 
Passif invoked by: 
PASSIF.86 FILE EXISTS(FOOOBAR.CS) # 
UDI error @1@CH encountered while performing assertion checking 


test 99998 failed 
Passif invoked by: 
PASSIF.86 STRING FOUND(ERROR 28)IN FILE(:F1:LOC86.MP2)# 
UDI error @@21H encountered while performing assertion checking 


2. Test Failure Reporting 


When a test fails, PASSIF appends an entry to the report 
file specifying: 


a. the name of the console input file 


b. the ordinal number of the test 
c. the assertion which caused the failure 


3. Test Result Report File 


The results of the tests performed by PASSIF will be 
reported in file ":F1l:REPORT.LOG". 
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The use of a "hardwired" output file contributes to the 


parallelism and understandability of testing procedures 
between users of PASSIF. 


Other methods of specifying the report file are less 
desirable. If the report file is specified in a "macrofile" 
which is read by PASSIF upon each of its invocations, a 
substantial performance penalty is incurred, especially with 
a hard disk system. 


If the report file is specified in PASSIF's command tail 
with a control or switch, then the command tail becomes 
cluttered, and loses its "readable-English" flavor. 


The user may change the report file specification in 
PASSIF, if absolutely necessary, by editing the load module, 
since the report file is specified therein by the string 
"REPORT FILE=:F1:REPORT.LOG". The difficulty of changing 
the report file specification is deliberate. 


4. Exceptional Conditions 
a. Unreadable Report File 


Since PASSIF must read the report file banner to 
"orient" itself (ascertain the current ordinal test number), 
an unreadable banner constitutes an exceptional condition. 


In such cases PASSIF will "re-initialize" the report 
file by inserting a new banner at the beginning of the 
report file. Whatever was already in the report file will, 
therefore, not be destroyed. 


The values of "TESTS PASSED", "TESTS FAILED", and "TOTAL 


TESTS EXECUTED" are all "initialized" to zero in the new 
banner. 


b. Syntax Error in Command Tail 


If there is a syntax error in PASSIF's command tail, 
then a “test failed" entry is made in the report file. The 
string "syntax error in command tail:" appears in the report 
file, followed by the offending command tail, up to the 
point where the error was detected, followed by a _ hash- 
mark. This is the standard command-tail error reporting 
mechanism used by most Intel products. 
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B. EXAMPLES OF LEGAL COMMANDS WITH EXPLANATIONS 
1. File Exists 
Example: 
PASSIF FILE EXISTS(:F1:T23.MP2) 
Action: 


PASSIF checks to see whether file ":f1:t23.mp2" exists. 
If the file does not exist, or the file exists, but has zero 
length, then a "failed assertion" response is triggered; 
else, the test passes. A file of zero length is considered 
to be a failure because the existence of sucha file is 
almost always an indication of an exceptional condition. 
However, if the file is a spool queue file, e.g. 
:SP:T45.LST, the length of the file is not considered. 

2. File Absent 
Example: 
PASSIF FILE_ABSENT(:F@:ERRORS) 
Action: 

PASSIF checks that file ":f£Q:errors" does not exist. 
Detection of a file of zero length, or greater, triggers a 
"failed assertion" response. 

3. Files Match 
Example: 
PASSIF FILES MATCH(:F1:T31A.0BJ,:F6:T31A.OUT) 
PASSIF checks whether the specified files are identical. 
4. String Found 
Example: 
PASSIF STRING FOUND("*** ERROR #217") IN FILE (:F1:P11T@1.LST) 
PASSIF STRING FOUND & 
("this is quite a long string which contains a """) & 
IN FILE (:F1:P11T@1.LST) 
PASSIF checks whether the specified string appears in 


the specified file. Notice that ampersand continuation is 
allowed between tokens, as per usual. 
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5. String Absent 
Example: 
PASSIF STRING ABSENT("ERROR") IN FILE(:F1:T22A.MP1) 
PASSIF checks whether the specified string is absent 
from the specified file. 


C. ADDITIONAL SEMANTICS FOR COMMAND TAIL SPECIFICATION 


1. Keyword Abbreviations 


The keywords may be abbreviated as follows: 


FILE EXISTS ==> FE 
FILE ABSENT ==> FA 
FILES MATCH ==> FM 
STRING FOUND ==> SF 
STRING ABSENT 229 SA 


2. Multiple Commands 
Multiple commands are not allowed in a single invocation 
of PASSIF. The only multiple entities (lists) allowed ina 
single command are the two filenames required in the 
"files match" command. 
3. Null Command Tail 


If the command tail to PASSIF consists only of blanks 
and tabs then PASSIF signs on and exits. 
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1. SUMMARY 


COMP compares two files (text or object) and displays the 
differences between them. 


COMP may be used to compare files which contain substantial 
differences. It is fast enough that finding a single byte 
mismatch is feasible. 


2. SAMPLE INVOCATION 


COMP :fl:good.fil to :fl:bad.fil & 
print(:fl:output.cmp) sync(3) 


In this example, the two text files are compared, and the 
portions which miscompare are displayed in file 
"s:flsoutput.cmp"”. "Sync(3)" means that 3 lines must match 
before COMP deems that the files have been resynchronized. 


3. ACTIONS PERFORMED 


COMP prints out the mismatching blocks of lines. For text 
files, the text is printed out following the line number. 
For object files, the hex representation of the record is 
printed out following the record number. 


4. OUTPUT FORMAT 


Each block of mismatched lines or object records is printed 
with the file name as the first line. Each succeeding line 
begins with the line number or the record number of the 
mismatched item. This is followed by the text of the line 
or the hex representation of the object record (sixteen 
bytes per line). 


5. INPUT FORMAT 


5.1 Text 


Text files are treated as having the line feed character 
(@AH) as the last character of each line. If the length of 
the longest line exceeds the buffer size, an error occurs 
(see the SIZE option). 
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5.2 Object 


Object files are a sequence of hex bytes. They are treated 
as a sequence of records, each having the form of a one byte 
type field, followed by a one word length field (low byte 
then high byte), followed by the remainder of the record. 
This remainder consists of the number of bytes in the length 
field. The size of the largest record (3 + the maximum 
length field) must not exceed the buffer size (see the SIZE 
option). If this happens, it is an error. 


6. EXAMPLE 


Given the "sample" command line specified above, and given 
that the text files to be compared contain: 


good.fil 


vo] 
° 
° 
Qu 
i] 
a 
3 
is) 
NOON ABPWNE 


bad line 1 

good line 2 
good line 3 
good line 4 
good bad line 5 
good line 6 
good line 7 
extra line 


then the following output will be placed in file 
":£l:output.cmp": 
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FILE # 1: :F1:GOOD.FIL 
1: good line l 
2: good line 2 


FILE # 2: :F1:BAD.FIL 
1: bad line 1 
2: good line 2 


FILE # 1: :F1:GOOD.FIL 
5: good line 5 
6: good line 6 
7: good line 7 


FILE # 2: :F1:BAD.FIL 
: good bad line 5 
6: good line 6 
: good line 7 
8: extra line 


FILES DIFFER 


7. INVOCATION SYNTAX 


COMP <filename> TO <filename> 
[ PRINT ( <filename> ) ] [ SYNC ( <number> ) J 
[ SIZE ( <number> ) J] [ OBJECT ] [ ICR ] 


<number> is a decimal number in the range allowed by the 
control. 


7.1 PRINT Control 


If the print control is present in the command line, then 
output is directed to the specified file. The default is to 
send the output to :CO: . The control abbreviation PR is 
also allowed. 


7.2 Synchronization (SYNC) Control 


The sync control specifies the number of lines (or records) 
that must match before COMP deems that the files have 
synchronized. The default synchronization value is 3. The 
value must be in the range of 1 to 255. Any larger value 
will be truncated to this range. A zero value will be 
ignored, causing the default to be used. 
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7.3 Buffer Size (SIZE) Control 


This sets the size of the program buffers for the two input 
files and is useful if comparing files with unusually long 
lines (or object records) or an unusually long stretch of 
differences. Each line (or record) must fit in the buffer. 
If differences are encountered between the two files, those 
differences plus the synchronization lines (or records) must 
fit in the buffers. Failure of either of these will cause 
COMP to abort with an error message. 


The default buffer size is 8192 bytes. The parameter for 
this control must be within the range of 1924 to 65535. Any 
larger values will be truncated to a word value. Any 
smaller values will be set to 1624. Note that performance 
will be better if the value selected is a multiple of 512. 


COMP will attempt to allocate, using DQSALLOCATE, two 
buffers, each of the size indicated. Insufficient memory in 
the system will cause DQSALLOCATE to indicate an error. 


7.4 OBJECT Control 


This control indicates that the two files to be compared are 
object files as described in section 5.2 . The default is 
to compare the files as text files as described in section 
5.1. The abbreviation OJ is allowed. 


7.5 Ignore Comment Records (ICR) CONTROL 


This control is used only when the OBJECT control is in 
affect. It instructs COMP to ignore the contents of comment 
records when comparing two object files. This allows a 
clean compare to occur when comparing files whose only 
difference is the version of the compiler that generated the 
object (compiler name and version number are typically 
stored in a comment record near the beginning of the object 
file). Note that if a comment record is present in one file 
and absent in the other, a difference will be flagged. It 
is the contents that is ignored, not the presence or absence 
of the record itself. 


7-6 Help (?) 


The question mark control '?' causes COMP to print outa 
short description of invocation parameters. 
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8. ERROR MESSAGES 


INSUFFICIENT ROOM TO SYNCHRONIZE 
TRY A LARGER BUFFER SIZE (SIZE OPTION) 


This indicates that the number of bytes needed to contain a 
string of differences plus the synchronization lines 
(records) was greater than the buffer size. Use the SIZE 
option to create larger buffers. 


INSUFFICIENT ROOM FOR LARGEST RECORD 
TRY A LARGER BUFFER SIZE (SIZE OPTION) 


This indicates that the number of bytes needed to contain 
the longest line (or largest record) was greater than the 
buffer size. Use the SIZE option to create larger buffers. 


BAD OPTION PARAMETER: # 
DECIMAL NUMBER EXPECTED 


The SYNC and SIZE options require a decimal value as a 


parameter. The option scanner encounterred a non-decimal 
character in the parameter. 
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REQUEST FOR READER’S COMMENTS 


intel’s Technical Publications Departments attempt to provide publications that meet the needs of all Intel product 
users. This form lets you participate directly in the publication process. Your comments will help us correct and 
improve our publications. Please take a few minutes to respond. 


Please restrict your comments to the usability, accuracy, readability, organization, and completeness of this publi- 
cation. If you have any comments on the product that this publication describes, please contact your Intel represen- 
tative. If you wish to order publications, contact the Intel Literature Department (see page ii of this manual). 


1. Please describe any errors you found in this publication (include page number). 


2. Does the publication cover the information you expected or required? Please make suggestions for improvement. 


3. Is this the right type of publication for your needs? Is it at the right level? What other types of publications are 
needed? 
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4. Did you have any difficulty understanding descriptions or wording? Where? 
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5. Please rate this publication on a scale of 1 to 5 (5 being the best rating). 
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This document is one of a series describing Intel products. Your comments on the back of this form will 
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comments and suggestions become the property of Intel Corporation. 
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